Troubleshooting

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

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:

​

“Secrets outdated. Please restart the squid”

sqd restart -n <name> -s <slot>

​

Stuck in Building, Deploying, or Starting

1. Install the current CLI and verify it:
   npm i -g @subsquid/cli@latest
   sqd --version
   
2. Build and run the exact project locally:
   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.
5. Inspect the relevant container:
   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
   

​

Healthy, but no new blocks are indexed

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

​

Works locally, but not in Cloud

• 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?

​

Models or columns are missing

sqd logs -n <name> -s <slot> -c db-migrate --since 1h

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.

​

Multi-processor status is missing

new TypeormDatabase({
  stateSchema: 'ethereum_processor',
})

select * from ethereum_processor.status;

​

Database query blocks indexing

• Move periodic aggregates to a background job.
• Add indexes for frequent filters and joins.
• Use a statement timeout.
• Break backfills into bounded, resumable batches.
• Inspect and tune update-heavy tables.

​

Out of disk space

scale:
  addons:
    postgres:
      storage: 250Gi
      autoresize: true
      autoresize_limit: 500Gi

​

API URL changes after deployment

https://<org>.squids.live/<name>@<slot>/api/graphql

https://<org>.squids.live/<name>:production/api/graphql

​

Manifest validation errors

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

​

Avoid destructive recovery