메뉴
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.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
Use when writing or editing config.yaml. Chain/contract structure, addresses, start_block, event selection, field_selection, custom event names, env vars, address_format, schema/output paths, YAML validation, and deprecated options.
Use when optimizing indexer speed or tuning sync performance. HyperSync, batch size, WebSocket realtime config, and preload optimization.
Use when indexing contracts deployed by factory contracts at runtime. contractRegister API, dynamic contract config (no address), async registration, and same-block event coverage.
Use when writing or editing event handlers. Handler registration, context API (entity CRUD, getWhere queries, chain, log), spread updates, indexer runtime API, and common pitfalls.
Use when deploying an indexer across multiple chains. Entity ID namespacing to avoid collisions, chain-specific configuration patterns, and the context.chain runtime API.
Use when needing transaction-level data in handlers. Configure field_selection to include transaction fields on events, and access via event.transaction. No native transaction handler — access through event handlers.
| 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"} |
Symptom: Type errors after editing schema.graphql or config.yaml.
pnpm codegen
Always run codegen after any schema or config change.
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.
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}
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.
"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.