feat: more actionable error messages (0xMiden#1462)

Author: igamigo

CHANGELOG.md

@@ -49,6 +49,7 @@
 * [BREAKING] Refactored transaction APIs to support more granular updates in the transaction lifecycle ([#1407](https://github.com/0xMiden/miden-client/pull/1407)).
 * Updated Dexie indexes and SQL schema; fixed sync-related transaction state bug ([#1452](https://github.com/0xMiden/miden-client/pull/1452)).
 * Started syncing output note nullifiers by default, to track when they are consumed ([#1452](https://github.com/0xMiden/miden-client/pull/1452)).
+* Expanded some `ClientError` variants to contain explanations and hints about the errors ([#1462](https://github.com/0xMiden/miden-client/pull/1462)). 
 
 ## 0.11.11 (2025-10-16)
 

Cargo.lock

@@ -95,7 +95,7 @@ fn read_note_file(filename: PathBuf) -> Result<NoteFile, CliError> {
     let mut _file = File::open(filename).and_then(|mut f| f.read_to_end(&mut contents))?;
 
     NoteFile::read_from_bytes(&contents)
-        .map_err(|err| CliError::Client(ClientError::DataDeserializationError(err)))
+        .map_err(|err| ClientError::DataDeserializationError(err).into())
 }
 
 // HELPERS

bin/miden-cli/src/commands/import.rs

@@ -344,7 +344,7 @@ async fn send<AUTH: TransactionAuthenticator + Sync>(
         .map_err(|e| CliError::Input(format!("note not found: {e}")))?;
     let note: Note = note_record
         .try_into()
-        .map_err(|e| CliError::Client(ClientError::NoteRecordConversionError(e)))?;
+        .map_err(|e| CliError::from(ClientError::NoteRecordConversionError(e)))?;
     let (_netid, address) = Address::decode(address).map_err(|e| CliError::Input(e.to_string()))?;
 
     client.send_private_note(note, &address).await?;

bin/miden-cli/src/commands/notes.rs

@@ -3,7 +3,14 @@ use std::error::Error;
 use miden_client::account::AddressError;
 use miden_client::keystore::KeyStoreError;
 use miden_client::utils::ScriptBuilderError;
-use miden_client::{AccountError, AccountIdError, AssetError, ClientError, NetworkIdError};
+use miden_client::{
+    AccountError,
+    AccountIdError,
+    AssetError,
+    ClientError,
+    ErrorHint,
+    NetworkIdError,
+};
 use miette::Diagnostic;
 use thiserror::Error;
 
@@ -27,9 +34,14 @@ pub enum CliError {
     #[error("asset error")]
     #[diagnostic(code(cli::asset_error))]
     Asset(#[source] AssetError),
-    #[error("client error")]
+    #[error("client error: {error}")]
     #[diagnostic(code(cli::client_error))]
-    Client(#[from] ClientError),
+    Client {
+        #[source]
+        error: ClientError,
+        #[help]
+        help: Option<String>,
+    },
     #[error("config error: {1}")]
     #[diagnostic(
         code(cli::config_error),
@@ -83,3 +95,10 @@ pub enum CliError {
     #[diagnostic(code(cli::transaction_error))]
     Transaction(#[source] SourceError, String),
 }
+
+impl From<ClientError> for CliError {
+    fn from(error: ClientError) -> Self {
+        let help = Option::<ErrorHint>::from(&error).map(ErrorHint::into_help_message);
+        CliError::Client { error, help }
+    }
+}

bin/miden-cli/src/errors.rs

@@ -11,7 +11,7 @@ use miden_client::builder::ClientBuilder;
 use miden_client::keystore::FilesystemKeyStore;
 use miden_client::note_transport::grpc::GrpcNoteTransportClient;
 use miden_client::store::{NoteFilter as ClientNoteFilter, OutputNoteRecord};
-use miden_client::{Client, DebugMode, IdPrefixFetchError};
+use miden_client::{Client, ClientError, DebugMode, IdPrefixFetchError};
 use miden_client_sqlite_store::ClientBuilderSqliteExt;
 use rand::rngs::StdRng;
 mod commands;
@@ -196,7 +196,7 @@ impl Cli {
             let client =
                 GrpcNoteTransportClient::connect(tl_config.endpoint.clone(), tl_config.timeout_ms)
                     .await
-                    .map_err(|e| CliError::Client(e.into()))?;
+                    .map_err(|e| CliError::from(ClientError::from(e)))?;
             builder = builder.note_transport(Arc::new(client));
         }
 

bin/miden-cli/src/lib.rs

@@ -1,5 +1,6 @@
 use alloc::string::{String, ToString};
 use alloc::vec::Vec;
+use core::fmt;
 
 use miden_lib::account::interface::AccountInterfaceError;
 use miden_objects::account::AccountId;
@@ -26,6 +27,34 @@ use crate::rpc::RpcError;
 use crate::store::{NoteRecordError, StoreError};
 use crate::transaction::TransactionRequestError;
 
+// ACTIONABLE HINTS
+// ================================================================================================
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ErrorHint {
+    message: String,
+    docs_url: Option<&'static str>,
+}
+
+impl ErrorHint {
+    pub fn into_help_message(self) -> String {
+        self.to_string()
+    }
+}
+
+impl fmt::Display for ErrorHint {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self.docs_url {
+            Some(url) => write!(f, "{} See docs: {}", self.message, url),
+            None => f.write_str(self.message.as_str()),
+        }
+    }
+}
+
+// TODO: This is mostly illustrative but we could add a URL with fragemtn identifiers
+// for each error
+const TROUBLESHOOTING_DOC: &str = "https://0xmiden.github.io/miden-client/cli-troubleshooting.html";
+
 // CLIENT ERROR
 // ================================================================================================
 
@@ -115,6 +144,106 @@ impl From<ClientError> for String {
     }
 }
 
+impl From<&ClientError> for Option<ErrorHint> {
+    fn from(err: &ClientError) -> Self {
+        match err {
+            ClientError::MissingOutputRecipients(recipients) => {
+                Some(missing_recipient_hint(recipients))
+            },
+            ClientError::TransactionRequestError(inner) => inner.into(),
+            ClientError::TransactionExecutorError(inner) => transaction_executor_hint(inner),
+            ClientError::NoteNotFoundOnChain(note_id) => Some(ErrorHint {
+                message: format!(
+                    "Note {note_id} has not been found on chain. Double-check the note ID, ensure it has been committed, and run `miden-client sync` before retrying."
+                ),
+                docs_url: Some(TROUBLESHOOTING_DOC),
+            }),
+            ClientError::StoreError(StoreError::AccountCommitmentAlreadyExists(commitment)) => {
+                Some(ErrorHint {
+                    message: format!(
+                        "Account commitment {commitment:?} already exists locally. Sync to confirm the transaction status and avoid resubmitting it; if you need a clean slate for development, reset the store."
+                    ),
+                    docs_url: Some(TROUBLESHOOTING_DOC),
+                })
+            },
+            _ => None,
+        }
+    }
+}
+
+impl ClientError {
+    pub fn error_hint(&self) -> Option<ErrorHint> {
+        self.into()
+    }
+}
+
+impl From<&TransactionRequestError> for Option<ErrorHint> {
+    fn from(err: &TransactionRequestError) -> Self {
+        match err {
+            TransactionRequestError::MissingAuthenticatedInputNote(note_id) => {
+                Some(ErrorHint {
+                    message: format!(
+                        "Note {note_id} was listed via `TransactionRequestBuilder::authenticated_input_notes(...)`, but the store lacks an authenticated `InputNoteRecord`. Import or sync the note so its record and authentication data are available before executing the request."
+                    ),
+                    docs_url: Some(TROUBLESHOOTING_DOC),
+                })
+            },
+            TransactionRequestError::NoInputNotesNorAccountChange => Some(ErrorHint {
+                message: "Transactions must consume input notes or mutate tracked account state. Add at least one authenticated/unauthenticated input note or include an explicit account state update in the request.".to_string(),
+                docs_url: Some(TROUBLESHOOTING_DOC),
+            }),
+            TransactionRequestError::StorageSlotNotFound(slot, account_id) => {
+                Some(storage_miss_hint(*slot, *account_id))
+            },
+            _ => None,
+        }
+    }
+}
+
+impl TransactionRequestError {
+    pub fn error_hint(&self) -> Option<ErrorHint> {
+        self.into()
+    }
+}
+
+fn missing_recipient_hint(recipients: &[Word]) -> ErrorHint {
+    let message = format!(
+        "Recipients {recipients:?} were missing from the transaction outputs. Keep `TransactionRequestBuilder::expected_output_recipients(...)` aligned with the MASM program so the declared recipients appear in the outputs."
+    );
+
+    ErrorHint {
+        message,
+        docs_url: Some(TROUBLESHOOTING_DOC),
+    }
+}
+
+fn storage_miss_hint(slot: u8, account_id: AccountId) -> ErrorHint {
+    ErrorHint {
+        message: format!(
+            "Storage slot {slot} was not found on account {account_id}. Verify the account ABI and component ordering, then adjust the slot index used in the transaction."
+        ),
+        docs_url: Some(TROUBLESHOOTING_DOC),
+    }
+}
+
+fn transaction_executor_hint(err: &TransactionExecutorError) -> Option<ErrorHint> {
+    match err {
+        TransactionExecutorError::ForeignAccountNotAnchoredInReference(account_id) => {
+            Some(ErrorHint {
+                message: format!(
+                    "The foreign account proof for {account_id} was built against a different block. Re-fetch the account proof anchored at the request's reference block before retrying."
+                ),
+                docs_url: Some(TROUBLESHOOTING_DOC),
+            })
+        },
+        TransactionExecutorError::TransactionProgramExecutionFailed(_) => Some(ErrorHint {
+            message: "Re-run the transaction with debug mode enabled , capture VM diagnostics, and inspect the source manager output to understand why execution failed.".to_string(),
+            docs_url: Some(TROUBLESHOOTING_DOC),
+        }),
+        _ => None,
+    }
+}
+
 // ID PREFIX FETCH ERROR
 // ================================================================================================
 

crates/rust-client/src/errors.rs

@@ -450,7 +450,7 @@ pub enum TransactionRequestError {
     #[error("specified authenticated input note with id {0} is missing")]
     MissingAuthenticatedInputNote(NoteId),
     #[error("a transaction without output notes must have at least one input note")]
-    NoInputNotes,
+    NoInputNotesNorAccountChange,
     #[error("note not found: {0}")]
     NoteNotFound(String),
     #[error("note creation error")]

crates/rust-client/src/transaction/request/mod.rs

@@ -29,6 +29,7 @@ miden-client = { default-features = false, features = ["testing", "tonic"], path
 # External dependencies
 console_error_panic_hook = { version = "0.1.7" }
 hex                      = { version = "0.4" }
+js-sys                   = { version = "0.3" }
 miden-core               = { version = "0.19.0" }                              # TODO: used only to access MastNodeExt trait, consider re-exporting through base/client crate
 rand                     = { workspace = true }
 serde-wasm-bindgen       = { version = "0.6" }

crates/web-client/Cargo.toml

@@ -1,8 +1,10 @@
 extern crate alloc;
 use alloc::sync::Arc;
+use core::error::Error;
 use core::fmt::Write;
 
 use idxdb_store::WebStore;
+use js_sys::{Function, Reflect};
 use miden_client::crypto::RpoRandomCoin;
 use miden_client::note_transport::NoteTransportClient;
 use miden_client::note_transport::grpc::GrpcNoteTransportClient;
@@ -11,6 +13,8 @@ use miden_client::testing::mock::MockRpcApi;
 use miden_client::testing::note_transport::MockNoteTransportApi;
 use miden_client::{
     Client,
+    ClientError,
+    ErrorHint,
     ExecutionOptions,
     Felt,
     MAX_TX_EXECUTION_CYCLES,
@@ -20,7 +24,6 @@ use models::script_builder::ScriptBuilder;
 use rand::rngs::StdRng;
 use rand::{Rng, SeedableRng};
 use wasm_bindgen::prelude::*;
-use wasm_bindgen_futures::js_sys::Function;
 
 pub mod account;
 pub mod export;
@@ -213,13 +216,29 @@ impl WebClient {
 
 fn js_error_with_context<T>(err: T, context: &str) -> JsValue
 where
-    T: core::error::Error,
+    T: Error + 'static,
 {
     let mut error_string = context.to_string();
-    let mut source = Some(&err as &dyn core::error::Error);
+    let mut source = Some(&err as &dyn Error);
     while let Some(err) = source {
-        write!(error_string, ": {err}").expect("writing to string should always succeeds");
+        write!(error_string, ": {err}").expect("writing to string should always succeed");
         source = err.source();
     }
-    JsValue::from(error_string)
+
+    let help = hint_from_error(&err);
+    let js_error: JsValue = JsError::new(&error_string).into();
+
+    if let Some(help) = help {
+        let _ = Reflect::set(&js_error, &JsValue::from_str("help"), &JsValue::from_str(&help));
+    }
+
+    js_error
+}
+
+fn hint_from_error(err: &(dyn Error + 'static)) -> Option<String> {
+    if let Some(client_error) = err.downcast_ref::<ClientError>() {
+        return Option::<ErrorHint>::from(client_error).map(ErrorHint::into_help_message);
+    }
+
+    err.source().and_then(hint_from_error)
 }