MulticallHistoricalDataUnavailable

Documentation for eth_defi.event_reader.multicall_batcher.MulticallHistoricalDataUnavailable exception.

exception MulticallHistoricalDataUnavailable

Bases: eth_defi.event_reader.multicall_batcher.MulticallNonRetryable

The selected RPC node cannot execute a Multicall at a historical block.

A node can return this exception even when it serves the latest block and ordinary contract calls correctly. It indicates that required historical state has been pruned, is missing from the provider’s rollup metadata store, or is temporarily stale. The Multicall request itself remains valid.

The exception is intentionally a MulticallNonRetryable for the current provider: the internal Multicall retry loop must not repeatedly halve the batch and reissue a request for state the endpoint cannot supply. It is recoverable at the caller level. Catch this exception around a checkpointed historical scan, rotate a different archive RPC URL to the first position in the MultiProviderWeb3Factory configuration, and rerun the affected chain. Preserve existing historical parquet rows until a replacement scan completes successfully.

The error classification includes Geth’s missing trie node, dRPC’s metadata is not found and Alchemy’s layer stale messages. In the Enzyme Arbitrum backfill on 2026-08-20, Alchemy returned layer stale (JSON-RPC -32000) at block 368,237,833. This is a documented example of an RPC archive-data gap, not a vault-level failure.

Parameters

  • message – Complete Multicall diagnostic message, including chain, block, active provider and the original JSON-RPC response.

  • status_code – HTTP status code when available.

  • headers – Last provider response headers when available, retained for diagnosis.

Carry completed outputs across historical-state provider rotation.

Archive failover must preserve successful earlier fragments while requesting only the unread suffix at the original historical block. An exhausted rotation remains a hard error rather than a contract revert.

Parameters

  • message – Provider’s unavailable-state diagnosis.

  • status_code – HTTP status when present.

  • headers – Last response headers retained for diagnosis.

  • completed_results – Ordered (success, return_data) prefix.

Returns

None.

__init__(message, status_code=None, headers=None, completed_results=None)

Carry completed outputs across historical-state provider rotation.

Archive failover must preserve successful earlier fragments while requesting only the unread suffix at the original historical block. An exhausted rotation remains a hard error rather than a contract revert.

Parameters

  • message (str) – Provider’s unavailable-state diagnosis.

  • status_code (Optional[int]) – HTTP status when present.

  • headers (Optional[dict]) – Last response headers retained for diagnosis.

  • completed_results (Optional[list[tuple[bool, bytes]]]) – Ordered (success, return_data) prefix.

Returns

None.

Return type

None

completed_results

Ordered (success, return_data) prefix already read before the archive gap.

__new__(**kwargs)
add_note(note, /)

Add a note to the exception

with_traceback(tb, /)

Set self.__traceback__ to tb and return self.