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

* **TRC20 Token Tracking** - Monitor token transfers and balances
* **Smart Contract Analysis** - Index contract deployments and interactions
* **Transaction Analytics** - Track high-volume transaction patterns

<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

#### Log decoding errors on Tron

* Verify that the log topics and data match the expected TRC20 or smart contract event format.

* Check that contract addresses are correctly formatted (Tron uses base58 encoding for addresses).

* Ensure that event data is being decoded according to the contract ABI.

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