indexer-troubleshooting

name	indexer-troubleshooting
description	Use when the indexer fails to start, codegen errors, types are stale, Docker or database issues, or something is not working. Common error messages and fixes.
metadata	{"managed-by":"envio"}

Troubleshooting

Stale Types / Codegen Issues

Symptom: Type errors after editing schema.graphql or config.yaml.

pnpm codegen

Always run codegen after any schema or config change.

Docker / Database Not Running

Symptom: pnpm dev fails with connection refused or database errors.

docker info  # check Docker is running

The indexer needs Docker for PostgreSQL. Start Docker and retry.

Environment Variables

All env vars MUST use the ENVIO_ prefix. The hosted service only exposes variables with this prefix at runtime.

# WRONG
rpc:
  - url: ${RPC_URL}

# CORRECT
rpc:
  - url: ${ENVIO_RPC_URL}

HyperSync Errors

Missing ENVIO_API_TOKEN: Required for HyperSync. Get an Envio API token at https://envio.dev/app/api-tokens, then set it in .env or shell environment.

Common Runtime Errors

"field not indexed" — getWhere only works on id and fields with @index in schema.graphql.

"entity is read-only" — Entities from context.Entity.get() are frozen. Spread to update: context.Entity.set({ ...entity, field: newValue }).

"Cannot find module 'envio'" — Run pnpm install.

Codegen output stale after config.yaml change — Run pnpm codegen again.