> ## 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.
* **Parachain Analytics** - Track events and calls across Substrate chains
* **Staking Dashboards** - Monitor validator performance and staking activity
* **Governance Tracking** - Index proposals, votes, and referenda
* **Cross-chain Bridges** - Monitor asset transfers between parachains

<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 SQD Network serves finalized blocks and is typically \~1000 blocks behind the tip. Recent and unfinalized blocks are seamlessly handled by the SDK from a complementary real-time data source (RPC, GraphQL, or HTTP API, depending on the chain) configured in your processor. Potential chain reorganizations are automatically handled under the hood, ensuring data consistency.

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?

Squid SDK can ingest unfinalized blocks directly from an RPC endpoint, making indexing real-time with minimal latency. Configure your RPC endpoint in the processor to enable real-time indexing of the latest blocks.

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

#### Event decoding errors on Substrate

* Ensure that the runtime version matches the block being indexed. Substrate events can change between runtime versions.

* Verify that the event name and pallet match the runtime metadata for the block range being indexed.

* Check that event arguments are being decoded in the correct order according to the runtime metadata.

### 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 the [`ss58` encoding library](https://github.com/subsquid/squid/tree/master/ss58).

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