kleros/foresight/indexer-troubleshooting

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}

RPC / HyperSync Errors

"rate limited" or timeout errors: See indexer-performance skill for RPC tuning parameters.

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.