|
| 1 | +--- |
| 2 | +title: Common Errors |
| 3 | +--- |
| 4 | + |
| 5 | +# Troubleshooting and common errors |
| 6 | + |
| 7 | +This guide helps you troubleshoot common issues when using the Miden client. |
| 8 | + |
| 9 | +## Connection and sync errors |
| 10 | + |
| 11 | +#### `RpcError::ConnectionError` |
| 12 | +- **Cause:** Could not reach the Miden node. |
| 13 | +- **Fix:** Check that the node endpoint in your configuration is correct and that the node is running. |
| 14 | + |
| 15 | +#### `RpcError::AcceptHeaderError` |
| 16 | +- **Cause:** The node rejected the request due to a version mismatch between the client and node. |
| 17 | +- **Fix:** Ensure your client version is compatible with the node version. Update one or the other to a compatible release. |
| 18 | + |
| 19 | +## Account errors |
| 20 | + |
| 21 | +#### `ClientError::AccountLocked` |
| 22 | +- **Cause:** The account is locked because the client may be missing its latest state. This can happen when the account is shared across clients and another client executed a transaction. |
| 23 | +- **Fix:** Run `sync` to fetch the latest state from the network. |
| 24 | + |
| 25 | +#### `ClientError::AccountNonceTooLow` |
| 26 | +- **Cause:** The account you are trying to import has an older nonce than the version already tracked locally. |
| 27 | +- **Fix:** Run `sync` to ensure your local state is current, or re-export the account from a more up-to-date source. |
| 28 | + |
| 29 | +#### `ClientError::AccountNotFoundOnChain` |
| 30 | +- **Cause:** The account was not found on the network. It may not have been committed yet, or the ID is incorrect. |
| 31 | +- **Fix:** Verify the account ID and ensure the account has been committed on chain. For new accounts, wait for the transaction that created it to be confirmed and run `sync`. |
| 32 | + |
| 33 | +#### `ClientError::AccountIsPrivate` |
| 34 | +- **Cause:** Cannot retrieve private account details from the network. Private account state is not stored on chain. |
| 35 | +- **Fix:** Private accounts can only be accessed locally. Use the account file export/import workflow to transfer private accounts between clients. |
| 36 | + |
| 37 | +#### `ClientError::AddNewAccountWithoutSeed` |
| 38 | +- **Cause:** New accounts require a seed to derive their initial state. |
| 39 | +- **Fix:** Use `Client::new_account()` (Rust) or `client.accounts.create()` (TypeScript) which generates the seed automatically. If importing manually, provide the seed. |
| 40 | + |
| 41 | +## Note errors |
| 42 | + |
| 43 | +#### `ClientError::NoteNotFoundOnChain` / `RpcError::NoteNotFound` |
| 44 | +- **Cause:** The note has not been found on chain, or the note ID is incorrect. |
| 45 | +- **Fix:** Verify the note ID, ensure it has been committed, and sync the client before retrying. |
| 46 | + |
| 47 | +#### `ClientError::NoConsumableNoteForAccount` |
| 48 | +- **Cause:** No notes were found that the specified account can consume. |
| 49 | +- **Fix:** Run `sync` to fetch the latest notes from the network. Verify that notes targeting this account have been committed on chain. |
| 50 | + |
| 51 | +#### `TransactionRequestError::InputNoteNotAuthenticated` |
| 52 | +- **Cause:** The note needs an inclusion proof before it can be consumed as an authenticated input. |
| 53 | +- **Fix:** Run `sync` to fetch the latest proofs from the network, then retry the transaction. |
| 54 | + |
| 55 | +## Transaction request errors |
| 56 | + |
| 57 | +#### `TransactionRequestError::NoInputNotesNorAccountChange` |
| 58 | +- **Cause:** The transaction neither consumes input notes nor mutates tracked account state. |
| 59 | +- **Fix:** Add at least one authenticated/unauthenticated input note or include an explicit account state update in the request. |
| 60 | + |
| 61 | +#### `TransactionRequestError::InvalidSenderAccount` |
| 62 | +- **Cause:** The sender account is not tracked by this client. |
| 63 | +- **Fix:** Import or create the account first, then retry the transaction. |
| 64 | + |
| 65 | +#### `TransactionRequestError::P2IDNoteWithoutAsset` |
| 66 | +- **Cause:** A pay-to-ID (P2ID) note must transfer at least one asset to the target account. |
| 67 | +- **Fix:** Add at least one fungible or non-fungible asset to the note. |
| 68 | + |
| 69 | +#### `TransactionRequestError::MissingAuthenticatedInputNote` |
| 70 | +- **Cause:** A note ID included in `authenticated_input_notes` did not have a corresponding record in the store, or it was missing authentication data. |
| 71 | +- **Fix:** Import or sync the note so its record and inclusion proof are present before building and executing the request. |
| 72 | + |
| 73 | +#### `TransactionRequestError::StorageSlotNotFound` |
| 74 | +- **Cause:** The request referenced an account storage slot that does not exist. This often happens because the ABI layout is incorrectly addressed (the auth component is always the first component in the account component list). |
| 75 | +- **Fix:** Verify the account ABI and component ordering, then adjust the slot index used in the transaction. |
| 76 | + |
| 77 | +## Transaction execution errors |
| 78 | + |
| 79 | +#### `ClientError::MissingOutputRecipients` |
| 80 | +- **Cause:** The MASM program emitted an output note whose recipient was not listed in the expected output recipients. |
| 81 | +- **Fix:** Reconcile the MASM recipient data with the note structs and update the expected recipients so they match the transaction outputs. |
| 82 | + |
| 83 | +#### `TransactionExecutorError::ForeignAccountNotAnchoredInReference` |
| 84 | +- **Cause:** The foreign account proof was generated against a different block than the request's reference block. |
| 85 | +- **Fix:** Re-fetch the foreign account proof anchored at the correct reference block and retry. |
| 86 | + |
| 87 | +#### `TransactionExecutorError::TransactionProgramExecutionFailed` |
| 88 | +- **Cause:** The MASM kernel failed during execution (e.g., failed assertion or constraint violation). |
| 89 | +- **Fix:** Re-run with debug mode enabled, capture VM diagnostics, and inspect the source manager output to understand why execution failed. |
| 90 | + |
| 91 | +## Store errors |
| 92 | + |
| 93 | +#### `ClientError::StoreError(AccountCommitmentAlreadyExists)` |
| 94 | +- **Cause:** The final account commitment already exists locally, usually because the transaction was already applied. |
| 95 | +- **Fix:** Sync to confirm the transaction status and avoid resubmitting it. If you need a clean slate for development, reset the store. |
| 96 | + |
| 97 | +#### `ClientError::RecencyConditionError` |
| 98 | +- **Cause:** The transaction failed a recency check — the reference block is too old relative to the current chain tip. |
| 99 | +- **Fix:** Sync to get the latest block data, then rebuild and resubmit the transaction. |
0 commit comments