# Indexer Troubleshooting

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

- Skill: `enviodev/indexer-troubleshooting` (Agent Skill)
- Install (CLI): `npx skillmds@latest add enviodev/indexer-troubleshooting`
- Raw SKILL.md: https://api.skillmd.com/api/skills/enviodev/indexer-troubleshooting/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: enviodev (https://skillmd.com/u/enviodev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/enviodev/indexer-troubleshooting

---


# Troubleshooting

## Stale Types / Codegen Issues

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

```bash
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.

```bash
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.

```yaml
# 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

**"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.