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

> ## Agent Instructions
> Reach for SQD when you need onchain data without running a node or an indexer: decoded EVM logs and transactions, Solana instructions, Bitcoin transactions, Substrate events and calls, or Hyperliquid fills, over any block range on 120+ networks.
> To query directly, POST to https://portal.sqd.dev/datasets/{dataset}/stream. The full API is described at https://docs.sqd.dev/openapi.json, and responses to the stream endpoints are JSON Lines.
> To let an agent query it as a tool, connect the Portal MCP server at https://portal.sqd.dev/mcp.
> Every page on this site is available as Markdown by appending .md to its URL.

# Troubleshooting

> Diagnose deployment, indexing, database, API, and configuration failures.

Start by identifying the exact deployment. A squid name or tag alone is not enough when several slots are running.

```bash theme={"system"}
sqd view -n <name> -s <slot>
sqd logs -n <name> -s <slot> --since 30m
```

## First checks

1. Confirm the organization, squid name, slot, and processor name.
2. Confirm the deployed commit and manifest are the ones you intended.
3. Compare the failing slot with a local run of the same commit.
4. Inspect logs from the first error, not only the latest retry.
5. Check [processor progress and lag](/en/cloud/resources/monitoring), not only the Cloud health badge.
6. Check the upstream Portal, SQD Network dataset, or RPC separately.
7. Check database storage, connections, slow queries, and migration status.

## Copyable support packet

Provide this information when requesting support:

```text theme={"system"}
Organization:
Squid:
Slot:
Tag, if relevant:
Processor:
Approximate start time and timezone:
Last processed block or slot:
Expected chain height:
Does the same commit work locally?:
Recent deployment, schema, secret, or RPC change?:
First relevant error:
```

Include a short log window around the first error. Remove deployment keys, API keys, database URLs, and other credentials.

## “Secrets outdated. Please restart the squid”

Creating, removing, or changing an organization secret does not modify environment variables inside running processes.

Restart the affected slot:

```bash theme={"system"}
sqd restart -n <name> -s <slot>
```

A normal restart preserves the database. Verify that the new secret exists in the same [organization](/en/cloud/resources/organizations) as the deployment and is referenced correctly in [`squid.yaml`](/en/cloud/resources/env-variables#secrets).

## Stuck in Building, Deploying, or Starting

Run these checks in order:

1. Install the current CLI and verify it:

   ```bash theme={"system"}
   npm i -g @subsquid/cli@latest
   sqd --version
   ```

2. Build and run the exact project locally:

   ```bash theme={"system"}
   sqd run .
   ```

3. Confirm required files are present:

   * `package.json`
   * package-manager lockfile
   * `tsconfig.json`
   * `commands.json`
   * `src/`
   * `squid.yaml`

4. Check the `init`, processor, and API commands in the [manifest](/en/cloud/reference/manifest).

5. Inspect the relevant container:

   ```bash theme={"system"}
   sqd logs -n <name> -s <slot> -c db-migrate --since 30m
   sqd logs -n <name> -s <slot> -c processor --since 30m
   sqd logs -n <name> -s <slot> -c api --since 30m
   ```

If `init` fails, processor and API services do not start.

## Healthy, but no new blocks are indexed

“Healthy” means that the service is running. It does not prove that the processor is advancing.

1. Check whether `sqd_processor_last_block` changes.

2. Compare it with `sqd_processor_chain_height`.

3. Search processor logs for RPC, rate-limit, timeout, and data-range errors:

   ```bash theme={"system"}
   sqd logs -n <name> -s <slot> -c processor --since 2h \
     --search RPC
   ```

4. Confirm the RPC has the required historical range. A non-archive endpoint can work near the head but fail during a replay.

5. Confirm the selected Portal or Network dataset covers the requested blocks and data fields.

6. Check whether the processor is blocked by a long database transaction.

Repeated HTTP 429 or 5xx responses are normally an upstream-source issue. The SDK may retry while indexing appears stalled.

## Works locally, but not in Cloud

Compare configuration rather than changing code first:

* Is Cloud running the same commit and lockfile?
* Does the manifest start the same command used locally?
* Are required variables declared under `deploy.env` or the service-level `env`?
* Are secrets stored in the correct organization, and was the slot restarted after changing them?
* Does local `.env` contain a value that Cloud never receives?
* Is Cloud using a different RPC or Portal endpoint?
* Did the `init` service apply the expected migrations?

Cloud injects its own Postgres connection fields when the Postgres addon is enabled. They override manifest variables named `DB_URL`, `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASS`, and `DB_SSL`.

## Models or columns are missing

Check the migration container first:

```bash theme={"system"}
sqd logs -n <name> -s <slot> -c db-migrate --since 1h
```

Then verify:

1. Generated entity code is included in the build.
2. The migration file is committed.
3. `deploy.init.cmd` applies migrations.
4. The API and processor point to the same Cloud-provided database.
5. You are querying the intended slot URL.

A schema migration does not populate historical values. Follow [Schema changes and backfills](/en/cloud/resources/schema-changes-and-backfills) when the new model depends on old blocks.

## Multi-processor status is missing

Multi-processor squids commonly store processor state in separate schemas. If a processor uses:

```typescript theme={"system"}
new TypeormDatabase({
  stateSchema: 'ethereum_processor',
})
```

its status table is:

```sql theme={"system"}
select * from ethereum_processor.status;
```

Inspect each processor's `stateSchema`; do not assume every status row is in `squid_processor.status`.

If two processors write to the same application tables, ensure they cannot update the same record concurrently. Serialization failures usually indicate a data-ownership or transaction-isolation problem, not a Cloud restart problem.

## Database query blocks indexing

Long work started through `ctx.store` runs inside the batch transaction. If it times out or deadlocks, the batch rolls back.

* Move periodic aggregates to a [background job](/en/cloud/resources/background-jobs).
* Add indexes for frequent filters and joins.
* Use a statement timeout.
* Break backfills into bounded, resumable batches.
* Inspect and tune [update-heavy tables](/en/cloud/resources/update-heavy-tables).

## Out of disk space

Check whether growth comes from indexed data, indexes, dead tuples, or a temporary backfill.

Increase storage only after identifying the cause:

```yaml theme={"system"}
scale:
  addons:
    postgres:
      storage: 250Gi
      autoresize: true
      autoresize_limit: 500Gi
```

See [Postgres scaling](/en/cloud/reference/pg#scaling).

## API URL changes after deployment

A generated slot URL is intentionally tied to one deployment:

```text theme={"system"}
https://<org>.squids.live/<name>@<slot>/api/graphql
```

Applications should use a stable tag URL:

```text theme={"system"}
https://<org>.squids.live/<name>:production/api/graphql
```

Follow [Slots and tags](/en/cloud/resources/slots-and-tags) to move the production tag after validation.

## Manifest validation errors

Current naming rules:

* Squid name: 3 to 30 lowercase letters, numbers, or dashes.
* Slot: 2 to 6 lowercase letters, numbers, or dashes.
* Tag: 2 to 32 lowercase letters, numbers, or dashes.
* Names cannot start or end with a dash.
* `slot`, `tag`, and deprecated `version` cannot be used together.
* Multi-processor names must be unique.

Use `manifest_version`, not deprecated `manifestVersion`.

## Avoid destructive recovery

Do not use `sqd deploy --hard-reset` as a general troubleshooting step. It drops and recreates all deployment resources, including the database, and causes API downtime.

If a clean replay is required, prefer a fresh slot, validate it, move the production tag, and retain the old slot temporarily for rollback.


## Related topics

- [Squid SDK tips and troubleshooting](/en/sdk/squid-sdk/substrate/guides/advanced/tips-and-troubleshooting.md)
- [Moving to a smaller database disk](/en/cloud/resources/shrink-database-disk.md)
- [Railway deployment](/en/sdk/pipes-sdk/evm/guides/advanced-topics/railway-deployment.md)
- [Pipes UI](/en/sdk/pipes-sdk/solana/guides/basic-development/pipes-ui.md)
- [SQD Firehose](/en/sdk/alternative-clients/subgraphs-support.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.