> ## 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.

# FAQ & Troubleshooting

> Frequently asked questions and common issues when developing with Squid SDK

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.
* **DEX Analytics** - Track swaps and liquidity pools across Solana DEXs
* **Program Analysis** - Monitor program interactions and account state changes
* **Real-time Bots** - Build bots with \~1-2 sec delay triggered by on-chain activity

<Tip>
  Squid SDK excels at applications requiring high-performance indexing, complex
  data transformations, and real-time processing.
</Tip>

### 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](guides/advanced/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`](reference/data-stores/typeorm-store) store their state in a PostgreSQL [schema](https://www.postgresql.org/docs/current/sql-createschema.html) (not a table). By default, the schema is called `squid_processor`.

<Note>
  The schema name must be overridden in [multiprocessor
  squids](guides/advanced/multichain-indexing).
</Note>

View sync status:

```sql theme={"system"}
SELECT * FROM squid_processor.status;
```

Reset processor status:

```sql theme={"system"}
DROP SCHEMA squid_processor CASCADE;
```

**File-based datasets**: Squids using [file-based storage](guides/other-data-destinations) store their status in `status.txt` by default. This can be customized via the `hooks` [database option](reference/data-stores/file-store#database-options).

#### 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`:

```json theme={"system"}
{
  "commands": {
    "serve:dev": {
      "cmd": ["npx", "squid-graphql-server", "--subscription"]
    }
  }
}
```

<Note>
  See
  [Subscriptions](reference/openreader/configuration/subscriptions)
  for detailed configuration options.
</Note>

#### 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`).

<Info>
  For squids deployed to SQD Cloud, metrics are publicly exposed. See
  [Monitoring in the Cloud](/en/cloud/resources/monitoring) for details.
</Info>

#### Do squids have a debug mode?

Yes. Enable debug mode by setting the `SQD_DEBUG` environment variable:

```bash theme={"system"}
# Enable all debug messages
SQD_DEBUG=*

# Enable specific namespace (e.g., SQD Network queries)
SQD_DEBUG=sqd:processor:archive
```

<Tip>
  Use specific namespaces to focus on particular components and reduce log noise
  during debugging.
</Tip>

## Troubleshooting

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

### Processor Issues

#### Instruction decoding errors on Solana

* Ensure that the instruction data matches the expected program IDL format. Verify that you're using the correct program ID and instruction discriminator.

* Check that the instruction accounts array matches the expected account layout for the instruction being decoded.

* If decoding fails, verify that the program IDL is up to date and matches the on-chain program version.

### 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](guides/writing-to-postgres#updating-after-schema-changes). The relevant commands are listed in the [`squid-typeorm-migration` reference](reference/typeorm-migration).

#### `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](guides/writing-to-postgres), 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.

#### `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`](https://github.com/subsquid/squid/tree/master/util/util-internal-hex) library. For addresses, use appropriate encoding for your chain type.

### GraphQL Issues

#### API queries are too slow

* Make sure all the necessary fields are [indexed](reference/schema-files/indexes-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](reference/openreader/configuration/dos-protection) for the incoming queries to protect against DoS attacks

#### `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](reference/openreader/configuration/dos-protection).