> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sqd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.sqd.dev/feedback

```json
{
  "path": "/en/sdk/squid-sdk/troubleshooting",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Squid SDK Troubleshooting

> Common issues, errors, and fixes for Squid SDK developers — schema migration failures, processor crashes, sync delays, and TypeScript build errors.

Many issues can be resolved by following the [best practices guide](/en/cloud/resources/best-practices) of SQD Cloud.

## Processor

<AccordionGroup>
  <Accordion title="`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 `Transfer`s.

    * 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.
  </Accordion>

  <Accordion title="`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](/en/sdk/squid-sdk/resources/tools/typegen/state-queries#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](/en/sdk/squid-sdk/tutorials/bayc/step-four-optimizations).
  </Accordion>
</AccordionGroup>

## Data sinks

<AccordionGroup>
  <Accordion title="`QueryFailedError: relation &#x22;...&#x22; 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](/en/sdk/squid-sdk/resources/persisting-data/typeorm#updating-after-schema-changes).
  </Accordion>

  <Accordion title="`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](/en/sdk/squid-sdk/resources/persisting-data/typeorm), 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](https://eslint.org/docs/latest/rules/require-await) eslint rule to be helpful.
  </Accordion>

  <Accordion title="`QueryFailedError: invalid byte sequence for encoding &#x22;UTF8&#x22;: 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`](https://github.com/subsquid/squid/tree/master/util/util-internal-hex) library. For addresses, use the [`ss58` encoding library](https://github.com/subsquid/squid/tree/master/ss58).
  </Accordion>
</AccordionGroup>

## GraphQL

<AccordionGroup>
  <Accordion title="API queries are too slow">
    * Make sure all the necessary fields are [indexed](/en/sdk/squid-sdk/reference/schema-file/indexes-and-constraints). The best way to do that is to perform the [query optimization procedure](/en/cloud/resources/query-optimization).
    * Annotate the schema and [set reasonable limits](/en/sdk/squid-sdk/reference/openreader-server/configuration/dos-protection) for the incoming queries to protect against DoS attacks
  </Accordion>

  <Accordion title="`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](/en/sdk/squid-sdk/reference/openreader-server/configuration/dos-protection).
  </Accordion>
</AccordionGroup>