Guides
SupportStatusSign UpLogin

EVM - trace_block and debug_traceBlockBy* Timeouts

When using the trace_block , debug_traceBlockByNumber, or debug_traceBlockByHash methods, you may encounter execution timeout errors.

Example request:

curl --location 'https://sonic-mainnet.gateway.tatum.io/' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {YOUR_API_KEY}' \
--data '{
    "jsonrpc": "2.0",
    "method": "debug_traceBlockByHash",
    "params": [
        "0xdf4b451b14728cec5b1f52a2b73dc45229f5afbc266a8c7abb0c219f755bfd3e",
        {
            "tracer": "callTracer",
            "timeout": "5m"
        }
    ],
    "id": 1
}'
//Response
{
    "id": 1,
    "jsonrpc": "2.0",
    "error": {
        "code": -32000,
        "message": "execution timeout"
    }
}

Cause

The methods trace_block , debug_traceBlockByNumber, and debug_traceBlockByHash are resource-intensive.

On blocks with many transactions, complex internal calls, or high gas usage, the node may time out before completing the request.

Using callTracer increases the load even further. On large blocks, the node may fail to return results even with long timeouts (e.g., "timeout": "5m").

trace_block vs. debug_traceBlockBy*

Key differences:

trace_block

  • Always produces a full trace of the block with all transactions.
  • Does not accept tracer options like callTracer or 4byteTracer.
  • Must replay every transaction in detail → inherently heavy.
  • Can time out on high-throughput chains (Polygon, BSC, Sonic) even without a custom tracer.

debug_traceBlockByNumber / debug_traceBlockByHash

  • More flexible: supports different tracers (callTracer, 4byteTracer, etc.) and timeout configuration.
  • Timeouts usually happen only when using heavy tracers like callTracer.
  • Using the lighter 4byteTracer often avoids timeouts.

Workarounds

1. Use a Lighter Tracer (Recommended)

If you don’t require full internal call details, switch to a more efficient tracer such as 4byteTracer. This extracts only function selectors (4-byte method signatures) and drastically reduces processing time.

Example using 4byteTracer:

curl --location 'https://sonic-mainnet.gateway.tatum.io/' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {YOUR_API_KEY}' \
--data '{
    "jsonrpc": "2.0",
    "method": "debug_traceBlockByHash",
    "params": [
        "0xdf4b451b14728cec5b1f52a2b73dc45229f5afbc266a8c7abb0c219f755bfd3e",
        {
            "tracer": "4byteTracer",
            "timeout": "5m"
        }
    ],
    "id": 1
}'
//Response:
{
    "jsonrpc": "2.0",
    "id": 1,
    "result": [
        {
            "txHash": "0xda8b7db420780ac9e606937517f09bf6ed3e679a98a28de3ae0387b5711064ec",
            "result": {
                "0x00000000-221": 1,
                "0x07a2d13a-32": 21,
                "0x07a2d13a-96": 13,
                "0x09...

2. Trace Individual Transactions

If you need internal call data, run the trace on single transactions rather than entire blocks.

Example using debug_traceTransaction:

curl --location 'https://ethereum-mainnet.gateway.tatum.io' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {YOUR_API_KEY}' \
--data '{
    "jsonrpc":"2.0",
    "method":"debug_traceTransaction",
    "params":["0xa1b562b91c6b2ba6a4fb099e1c85000dff85d7cbe7d5aaa883c9eb9a49e258c7",
        {
            "tracer":"callTracer",
            "timeout": "90s"
        }
    ],
    "id":1
}'

Updated 12 days ago