query timeout exceeded
-32005 query timeout exceeded
Infura documents this as the eth_getLogs answer when a query runs past its 10-second limit, under
the same code as query returned more than 10000 results
(Infura’s eth_getLogs reference).
Many endpoints do not send an error at all: the connection stays open until the client gives up, or a
proxy in front of the node closes it, and what you see is your HTTP library’s timeout.
Why it happens
The usual cause is a query from block 0 to latest. In ethers that is
contract.queryFilter(filter, 0, 'latest'), often written with fromBlock defaulting to 0. The node
has to look at every block since genesis, more than 20 million on Ethereum, even if the contract was
deployed last month. On a shared endpoint that is refused for range, refused for results, or simply
not finished in time.
It gets worse when the query sits behind a page. A dashboard that calls it on every load sends the
whole history scan again each time anyone opens or refreshes it.
StabilityNexus/Windmill-EVM-WebUI#132
is this shape: three queryFilter calls from block 0 on each dashboard refresh, against public
endpoints.
The fix without Nuthatch
- Start at the contract’s deployment block. Record it in your config, or find it once with a binary
search over
eth_getCode. - Walk from there to the head in windows the endpoint accepts (see exceed maximum block range), narrowing a window that times out.
- Keep the results, with the last block you have, in a store of your own. On the next load fetch only the blocks after it.
- Serve the page from that store, not from the RPC.
By step 4 you have written a small indexer, which is a reasonable thing to have.
What a nest does
A nest is that indexer. nuthatch init finds the deployment block by binary search over eth_getCode
and writes it to nuthatch.toml as start_block; if the endpoint keeps no old state it prints
deployment block undetected and asks for --start-block rather than starting from 0.
nuthatch dev reads the history once, in adaptive windows, keeps it on disk, and follows the head
from there, so a restart resumes from the last block it has.
A window the endpoint cannot answer in time is narrowed, not retried whole. Since 5.18.0 that holds for
a request that gets no response within the client’s 20-second timeout, as well as for one whose body
is too slow to read, and Infura’s query timeout exceeded is read as a range too large. A single block
that still times out is waited on and retried, since it cannot be split.
The dashboard then reads the local copy, which answers without asking the chain:
nuthatch init 0xYourContract --chain mainnet --rpc https://your-endpoint.example
nuthatch dev
curl 'http://127.0.0.1:8288/sql?q=SELECT%20count(*)%20FROM%20yourcontract__order_filled'
The table name is the alias init chose and the event in snake case, so OrderFilled becomes
order_filled; schema.json in the nest lists every table. See the HTTP API for /sql and the per-event routes, and
Serving for putting it behind a proxy when the page is public.
Checked against Nuthatch 5.22.0 (2026-11-17). Verify a release-specific command with the CLI reference before running it in production.