EVM - trace_block and debug_traceBlockBy* Timeouts

Tracing full blocks is computationally expensive. When using trace_block, debug_traceBlockByNumber, or debug_traceBlockByHash, you may encounter:

execution timeout

🚧

Attention

Tatum Gateway enforces a hard 120 second request ceiling, regardless of any custom timeout you provide in the request payload.

Example request:

• Block on Sonic Mainnet: https://sonicscan.org/block/37616150

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"
    }
}

Why This Happens

Tracing methods such as trace_block , debug_traceBlockByNumber, and debug_traceBlockByHash are resource-intensive. When blocks are large, contain many internal calls, or originate from high-throughput networks (Polygon, BSC, Sonic), the node must process significant computation.

Adding callTracer increases the load even further. Even long custom timeouts like "5m" cannot override the Gateway’s 120-second cap.

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 usingdebug_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
}'