Skip to main content
Common questions and solutions for developing with Squid SDK.

​
Frequently Asked Questions

​
Real-World Applications

​
What are some real-world applications for which Squid SDK was a good fit?

Squid SDK is well-suited for a wide range of blockchain indexing applications:
  • DeFi Backends - UIs and dashboards for a variety of dApps, including DEXs, NFT marketplaces etc.
  • Historical Price Feeds - Track Uniswap trades and Chainlink oracle contracts
  • Smart Contract Analysis - Mine contract deployments and analyze bytecode
  • Real-time Bots - Build bots with ~1-2 sec delay triggered by on-chain activity
Squid SDK excels at applications requiring high-performance indexing, complex data transformations, and real-time processing.

​
Technical Questions

​
How does Squid SDK handle unfinalized blocks?

The Portal stream serves blocks all the way to the chain tip, including unfinalized ones. Run the source with a hot-block-aware database (TypeormDatabase({supportHotBlocks: true})) and chain reorganizations are rolled back automatically — handler code never sees forks. For detailed information, see Indexing unfinalized blocks.

​
How do squids keep track of their sync progress?

Sync progress tracking depends on the data sink used: TypeORM Database: Processors using TypeormDatabase store their state in a PostgreSQL schema (not a table). By default, the schema is called squid_processor.
The schema name must be overridden in multiprocessor squids.
View sync status:
Reset processor status:
File-based datasets: Squids using file-based storage store their status in status.txt by default. This can be customized via the hooks database option.

​
How fresh is the data served by squids?

The Portal stream serves unfinalized blocks in real time, so indexing latency is minimal out of the box — no extra configuration needed. Typically you’ll see the data in under 1 s from the time it becomes available via RPC, though larger delays are possible in some cases.

​
How do I enable GraphQL subscriptions for local runs?

Add the --subscription flag to the serve command in your commands.json:
See Subscriptions for detailed configuration options.

​
Is there a healthcheck endpoint for the indexer?

Yes! The processor exposes Prometheus metrics at the /metrics endpoint (port from PROCESSOR_PROMETHEUS_PORT, falling back to PROMETHEUS_PORT).
For squids deployed to SQD Cloud, metrics are publicly exposed. See Monitoring in the Cloud for details.

​
Do squids have a debug mode?

Yes. Enable debug mode by setting the SQD_DEBUG environment variable:
Use specific namespaces to focus on particular components and reduce log noise during debugging.

​
Troubleshooting

Many issues can be resolved by following the best practices guide of SQD Cloud.

​
Processor Issues

​
Error: data out-of-bounds ethers errors on EVM

  • Usually this means that you’re using the decoder on the wrong data. Make sure that the decoder receives only the data you intend it to. Example: suppose you want to add the processing of a Mint event to a squid that is currently processing only Transfer events. You change the processor configuration to get the Mint events for you, but you forget to sort the events in the batch handler and a data item with a Mint event finds its way into a decoder of Transfers.
  • Another common source of this error is faulty RPC endpoints. If your EVM processor crashes during RPC ingestion on a log with '0x' in its data field, try switching to another RPC provider or, if you are developing locally, to another Ethereum network emulator.

​
BAD_DATA when using a Multicall contract

This error can occur for a variety of reasons, but one common cause is choosing a Multicall deployment that is newer than the oldest blocks that have to be indexed. When batch state queries are performed on historical chain state older than the Multicall deployment, EVM detects that and refuses to run. Solutions:
  1. Use an older Multicall deployment.
  2. Delay your chain state queries until a later block.
These issues are explored in Part 4 of the BAYC tutorial.

​
Data Sink Issues

​
QueryFailedError: relation "..." does not exist

It is likely that the generated migrations in the db/migrations folder are outdated and do not match the schema file. Recreate the migrations from scratch as detailed on this page. The relevant commands are listed in the squid-typeorm-migration reference.

​
Query runner already released. Cannot run queries anymore, or too late to perform db updates, make sure you haven't forgot to await on db query

If your squid saves its data to a database, all operations with ctx.store are asynchronous. Make sure you await on all store operations like upsert, update, find, save etc. You may find the require-await eslint rule to be helpful.

​
QueryFailedError: invalid byte sequence for encoding "UTF8": 0x00

PostgreSQL doesn’t support storing NULL (\0x00) characters in text fields. Usually the error occurs when a raw bytes string (like UIntArray or Bytes) is inserted into a String field. If this is the case, use hex encoding, e.g. using util-internal-hex library. For addresses, use appropriate encoding for your chain type.

​
GraphQL Issues

​
API queries are too slow

​
response might exceed the size limit

Make sure the input query has limits set or the entities are decorated with @cardinality. We recommend using XXXConnection queries for pagination. For configuring limits and max response sizes, see DoS protection.