| name | midnight-status-codes:status-codes |
| description | Use when an agent encounters a Midnight error code, error message, or error type and needs to identify what it means, what component produced it, and how to fix it. Routes to the correct reference file based on error source and characteristics. Covers numeric node error codes (0-255), TypeScript SDK error classes, Effect tagged wallet errors, Compact compiler diagnostics, ZK proof errors, ledger validation errors, proof server HTTP errors, indexer GraphQL errors, and DApp Connector API errors. |
Midnight Error Code Routing
When you encounter a Midnight error, use this decision tree to find the right reference file.
Quick Lookup
For the fastest path, use the lookup command instead of reading reference files:
/midnight-status-codes:lookup <code-or-search-term>
Decision Tree
1. Numeric code (0-255) from a node or transaction submission
Read references/node-errors.md
These are LedgerApiError codes that surface via Substrate's InvalidTransaction::Custom(u8) in Substrate transaction validation. The reference file has the complete code table organized by range.
Recognise by: A bare number in an error message from the Midnight node, transaction pool rejection, or DispatchError::Module output.
2. TypeScript error class from @midnight-ntwrk/midnight-js-*
Read references/sdk-errors.md
Recognise by: Error class names like TxFailedError, DeployTxFailedError, CallTxFailedError, ContractTypeError, InvalidProtocolSchemeError, PrivateStateImportError, IndexerFormattedError, IndexerError, IndexerQueryError, IndexerDataError, IndexerSubscriptionDataError, IndexerProviderConfigError. These are standard JavaScript Error subclasses thrown by the midnight-js SDK packages.
3. Effect tagged error with _tag like Wallet.*
Read references/wallet-errors.md
Recognise by: Error objects with a _tag field matching patterns like Wallet.Other, Wallet.InsufficientFunds, Wallet.Transacting, SubmissionError, ConnectionError, TransactionInvalidError. These are Effect Data.TaggedError instances from the wallet SDK.
4. Effect typed error from @midnight-ntwrk/compact-js
Read references/sdk-errors.md
Recognise by: Error type names ContractRuntimeError, ContractConfigurationError, ZKConfigurationReadError, ConfigError, ConfigCompilationError, ParseError. These use Symbol.for() TypeIds and are part of the compact-js Effect error system.
5. Compact compiler message with source location
Read references/compiler-errors.md
Recognise by: Error messages with file path, line number, and character position (e.g., /path/to/file.compact line 42 char 5:). Also compiler exit codes (0, 1, 254, 255) and messages like "unbound identifier", "parse error: found X looking for Y", "potential witness-value disclosure".
6. Runtime error from compiled contract execution
Read references/runtime-errors.md
Recognise by: CompactError class name in the stack frame, or message prefixes "failed assert:", "type error:", "range error at", "expected ...", "Version mismatch:", "Maximum field mismatch:", "State map ...", "State ... cannot be cast to", or "Expected 32-byte string". Notably no file/line/char source location — these come from @midnight-ntwrk/compact-runtime, not the compiler.
7. ZK proof error mentioning PLONK, circuit, ZKIR, or verification
Read references/zk-errors.md
Recognise by: Error messages containing "Synthesis error", "constraint system", "NotEnoughRowsAvailable", "The SRS ... does not match for the given circuit", "invalid witness", PLONK-related terms, or proof verification failures.
8. Transaction validation or malformed transaction error (Rust-level)
Read references/ledger-errors.md
Recognise by: Rust error names like MalformedTransaction, TransactionInvalid, OnchainProgramError, TranscriptRejected, MalformedOffer, or messages about binding commitments, sequencing checks, effects mismatches.
9. HTTP status code from the proof server
Read references/proof-server-errors.md
Recognise by: HTTP status codes (400, 428, 429, 500, 503) from requests to port 6300 or a proof server URL. Also job status messages like "job queue full" or "bad input".
10. GraphQL error or HTTP status from the indexer
Read references/indexer-errors.md
Recognise by: GraphQL error responses from port 8088 or an indexer URL. Messages like "invalid block hash", "invalid viewing key", "indexer has not yet caught up with the node". HTTP status codes 400, 413, 503 from the indexer API.
11. DApp Connector APIError
Read references/dapp-connector-errors.md
Recognise by: Error objects with type: 'DAppConnectorAPIError' and a code field matching Disconnected, InternalError, InvalidRequest, PermissionRejected, or Rejected.
12. Not sure which source
If the error doesn't clearly match any category above:
- Try the lookup command:
/midnight-status-codes:lookup <error-text-or-code>
- Search by keyword:
/midnight-status-codes:lookup --search "<key-phrase>"
- If still not found, the error may be from a dependency (Substrate, Effect, Polkadot.js) rather than Midnight-specific code.
