nautechsystems/nautilus_trader · error

debug_traceTransaction RPC error {code}

Error message

debug_traceTransaction RPC error {code}

What it means

Raised by `trace_probe_result` (used by `probe_call_trace` via `debug_traceTransaction` with `callTracer`) when the node returns JSON-RPC error code -32601 (method not found) or -32602 (invalid params) for the trace request. It indicates the endpoint cannot serve `debug_traceTransaction` at all, rather than a per-transaction failure.

Source

Thrown at crates/adapters/blockchain/src/rpc/http.rs:993

        })
}

fn block_parameter(block: Option<u64>) -> serde_json::Value {
    block.map_or_else(
        || serde_json::json!("latest"),
        |number| serde_json::json!(format!("0x{number:x}")),
    )
}

#[cfg(feature = "hypersync")]
fn eth_call_error_is_revert(code: i32, message: &str) -> bool {
    code == 3 || message.to_ascii_lowercase().contains("revert")
}

#[cfg(feature = "hypersync")]
fn trace_probe_result(code: i32) -> anyhow::Result<()> {
    if matches!(code, -32_601 | -32_602) {
        anyhow::bail!("debug_traceTransaction RPC error {code}");
    }
    Ok(())
}

fn rpc_response_preview(raw_response: &str) -> String {
    if raw_response.len() <= 500 {
        return raw_response.to_string();
    }

    let mut end = 500;
    while !raw_response.is_char_boundary(end) {
        end -= 1;
    }
    format!(
        "{}... (truncated, {} bytes total)",
        &raw_response[..end],
        raw_response.len()
    )

View on GitHub (pinned to 18893faf8b)

Solutions

1. Use an RPC endpoint that supports debug/trace APIs (archive provider or self-hosted node with `debug` module enabled).
2. On self-hosted Geth, enable it: `--http.api eth,net,web3,debug` and `--syncmode full` (or archive).
3. If -32602, check the tracer name/options (`callTracer` config) match the client version.
4. Fall back to an alternative tracing method (e.g. trace_block/ots APIs) if the provider can't enable debug.

Example fix

// geth flags: before
geth --http --http.api eth,net,web3
// after
geth --http --http.api eth,net,web3,debug --gcmode archive --syncmode full

// Probe debug API availability before tracing
let ok: Result<String, _> = provider.request("debug_traceTransaction", (B256::ZERO, serde_json::json!({"tracer": "callTracer"}))).await;
let tracing_available = ok.is_ok() || !matches!(err_code(&ok), Some(-32601 | -32602));

fn is_unsupported_method(err: &anyhow::Error) -> bool {
    err.to_string().contains("RPC error -32601") || err.to_string().contains("RPC error -32602")
}

match probe_call_trace(...).await {
    Err(e) if is_unsupported_method(&e) => fallback_to_event_log_reconstruction(tx),
    other => other,
}

When it happens

Trigger: Calling `probe_call_trace`/`trace_probe_result` against a node that doesn't implement `debug_traceTransaction` (-32601) or rejects its tracer params (-32602).

Common situations: Using a public/load-balanced RPC that disables debug APIs; pointing at Erigon/Nethermind configurations with different tracer support; missing `--http.api debug,eth` flag on a self-hosted Geth.

Related errors

• Finalized block {} does not contain transaction {}
• eth_call execution reverted
• eth_call RPC error {code}
• eth_call RPC error {}
• eth_getTransactionReceipt returned a receipt with a mismatch

AI-assisted analysis of nautechsystems/nautilus_trader@18893faf8b (2026-09-08). Data as JSON: /api/errors/3c12b6915841a299. Report an issue: GitHub.