nautechsystems/nautilus_trader · error

eth_getTransactionReceipt returned a receipt with a mismatch

Error message

eth_getTransactionReceipt returned a receipt with a mismatched transaction hash

What it means

Safety check in `get_transaction_receipt`: after fetching a receipt via `eth_getTransactionReceipt`, the library verifies the returned receipt's `transaction_hash` matches the requested hash and fails otherwise. This guards against buggy or malicious RPC providers (or load balancers) returning a receipt for a different transaction.

Source

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

    /// A `null` result maps to `Ok(None)`: the transaction is pending and no receipt
    /// exists yet.
    ///
    /// # Errors
    ///
    /// Returns an error if the RPC call fails or the response is malformed.
    pub async fn get_transaction_receipt(
        &self,
        tx_hash: &B256,
    ) -> anyhow::Result<Option<RpcTransactionReceipt>> {
        let receipt: Option<RpcTransactionReceipt> = self
            .execute_execution_rpc_call("eth_getTransactionReceipt", serde_json::json!([tx_hash]))
            .await?;

        if receipt
            .as_ref()
            .is_some_and(|receipt| receipt.transaction_hash != *tx_hash)
        {
            anyhow::bail!(
                "eth_getTransactionReceipt returned a receipt with a mismatched transaction hash"
            );
        }

        Ok(receipt)
    }

    /// Returns a full transaction by hash.
    ///
    /// A `null` result maps to `Ok(None)` while the transaction is not available.
    ///
    /// # Errors
    ///
    /// Returns an error if the RPC call fails, the response is malformed, or the returned hash
    /// does not match `tx_hash`.
    #[cfg(feature = "hypersync")]
    #[allow(
        dead_code,

View on GitHub (pinned to 18893faf8b)

Solutions

1. Switch to a reputable RPC provider/endpoint and retry the lookup.
2. Bypass any caching/mutating proxy or middleware in the RPC path.
3. Check adapter/provider version for known hash-serialization bugs and update.
4. If polling, ensure the same tx hash string (case/0x-prefix) is used consistently.

// Sanity-check the requested hash before lookup
fn valid_tx_hash(h: &str) -> bool { h.len() == 66 && h.starts_with("0x") && h[2..].chars().all(|c| c.is_ascii_hexdigit()) }

fn receipt_matches(receipt: &TransactionReceipt, tx_hash: &Hash) -> bool {
    receipt.transaction_hash == *tx_hash
}

let receipt = match rpc.get_transaction_receipt(tx_hash).await {
    Ok(r) => r,
    Err(e) if e.to_string().contains("mismatched transaction hash") => {
        warn!("provider returned wrong receipt; retrying on fallback");
        fallback_rpc.get_transaction_receipt(tx_hash).await?
    }
    Err(e) => return Err(e),
};

When it happens

Trigger: Calling `get_transaction_receipt(tx_hash)` (typically via `poll_for_receipt`) and the node responds with a receipt whose `transaction_hash` differs from the requested one.

Common situations: Misbehaving or caching RPC proxy; provider bug after an upgrade; hash serialization mismatch in a custom middleware that rewrites hashes.

Understand the failure class

Background: "invalid response format", "malformed payload", "missing data field": when an API returns 200 but the response shape is wrong — this error's family across 23 libraries.

Related errors

• eth_getTransactionByHash returned a mismatched transaction h
• Finalized block {} does not contain transaction {}
• eth_call execution reverted
• eth_call RPC error {code}
• eth_call RPC error {}

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