For AI agents: the documentation index is at /llms.txt. Markdown versions of pages are available by appending .md to the URL.
Skip to main content

Common Issues and Troubleshooting

This guide helps you identify and resolve common issues you might encounter when working with Envio HyperIndex. If you don't find a solution to your problem here, please join our Discord community for additional support.

For build, deployment and access problems on Envio Cloud, see Envio Cloud Troubleshooting.

Table of Contents​

Setup and Configuration Issues​

Cannot find module errors on pnpm start​

Problem: Errors like Cannot find module when starting your blockchain indexer, or type errors such as Module "envio" has no exported member.

Cause: Dependencies aren't installed, the generated types are missing, or a handler still imports from the V2 generated package.

Solution:

  1. Install dependencies with pnpm install
  2. Run the code generation command, which writes the types to .envio/ and envio-env.d.ts:
pnpm codegen
  1. If the error names generated, import from "envio" instead. V3 has no generated package; see Migrate to V3.

Important: Run pnpm codegen after cloning an indexer repository, so your editor and tests see the types. pnpm dev and pnpm start run codegen for you.

Using Envio inside a monorepo​

Problem: Your indexer lives inside a larger monorepo and you see Cannot find module errors even after running pnpm codegen.

Cause: The indexer isn't part of the workspace, so its dependencies, including envio, aren't installed.

Solution: Add the indexer directory to the packages list in pnpm-workspace.yaml, for example:

packages:
  - "apps/*"
  - "packages/*"
  - "envio-indexer"

V3 has no generated package, so remove any envio-indexer/generated entry left over from V2. The handlers also need "type": "module" in the nearest package.json; see ES module errors.

Config parsing errors​

Codegen, envio dev and envio start all stop on an invalid config.yaml. The most common messages:

Message (excerpt)Fix
chains[0]: missing field `start_block` Add start_block to every chain. It is required.
chains[0].id: invalid type: string "...", expected u64Use the numeric chain ID, not a chain name. Check ${VAR} values too.
The RPC url "wss://..." is incorrect formaturl must be http(s)://. Put a WebSocket URL in the ws field.
Failed to automatically find HyperSync endpoint for the chain <id>The chain has no default HyperSync endpoint. Add an RPC with for: sync, or set hypersync_config.url.
Cannot define both hypersync_config and rpc as a data-source for historical syncRemove one, or set the RPC to for: fallback.
Environment variables are not present: <NAME>Set the variable, or give it a default: ${NAME:-default}.
No abi file provided for event <Event>Use a full event signature, or set abi_file_path on the contract.
has invalid address "...". Expected a 20-byte hex string starting with 0x.Fix the address in config.yaml.

Non-interactive envio init fails​

Problem: envio init run by a script, CI or an AI agent fails with The input device is not a TTY, Running non-interactively but no project directory was provided, or no Envio API token was provided.

Cause: Without a terminal, envio init can't prompt, so every value must come from flags.

Solution: Pass the subcommand with all its flags, plus -d and an API token (--api-token or ENVIO_API_TOKEN). contract-import explorer -b takes a network name such as ethereum-mainnet, not a chain ID. See Non-interactive envio init.

ES module errors on start​

Problem: The indexer fails to start with an ES module error, often after upgrading to V3. Current versions report one of these:

  • <file> can't load: envio handlers are ES modules, and <path>/package.json doesn't declare them. Add "type": "module" to it.
  • <file> can't load: envio handlers are ES modules, and no package.json above it declares them. Add one with "type": "module".

Older versions can fail with Error [ERR_REQUIRE_CYCLE_MODULE]: Cannot require() ES Module <file> in a cycle instead.

Cause: HyperIndex V3 loads your handlers as ES modules. A TypeScript handler (.ts/.tsx) only loads as one when the nearest package.json above it has "type": "module".

Solution: Add "type": "module" to that package.json, usually the one in your indexer's root. If there is no package.json above the handler, create one:

{
  "type": "module"
}

In a monorepo, the package.json that counts is the nearest one above your handler files. See Migrate to V3 for the other package.json changes V3 needs.

Smart contract updated after the initial codegen​

Problem: Changes to smart contracts aren't reflected in your blockchain indexer.

Cause: When smart contracts are modified after initial setup, the ABIs need to be regenerated and the indexer needs to be updated.

Solution:

  1. Re-export smart contract ABIs (example using Hardhat):
cd contracts/
pnpm hardhat export-abi
  1. Verify that the ABI directory in config.yaml points to the correct location where ABIs were freshly generated
  2. Run codegen again:
pnpm codegen

Events with struct (tuple) parameters​

Problem: An event has a struct parameter (a tuple in the ABI), maybe with structs nested inside it, and you're not sure how to write its signature in config.yaml or read it in a handler.

Solution: In the event signature, write each struct as its fields in parentheses, each with a type and a name. Structs can be nested, and [] after the parentheses makes an array of structs:

events:
  - event: "OrderFilled(bytes32 indexed orderId, (address maker, (address token, uint256 amount) asset) order)"

In the handler, a struct parameter is an object keyed by field name, nested the same way. An array of structs is an array of these objects:

const { maker, asset } = event.params.order;
const amount = asset.amount; // bigint

A field with no name is keyed by its position instead, for example event.params.order["0"].

Using the correct version of Node.js​

Problem: Compatibility issues or unexpected errors when running the indexer.

Solution: Envio requires Node.js 22.15.0 or newer. If you're on an older version, please update:

# Using nvm (recommended)
nvm install 22
nvm use 22

# Or download directly from https://nodejs.org/

Runtime Issues​

Config changes are incompatible with the existing indexer data​

Problem: The indexer refuses to start with:

The following config changes are incompatible with the existing indexer data:

    - <changed path>

Pick one:
  1. Revert the changes above  # resume indexing where it left off
  2. envio dev -r              # delete all indexed data and start over
  3. Run a second indexer alongside this one - keep both datasets:
       ENVIO_PG_SCHEMA=<new_schema> \
       ENVIO_INDEXER_PORT=<new_port> \
       envio dev

Cause: The database holds data indexed with a different config, schema or envio version. Restarts resume from the last checkpoint, so changes such as a new entity field, a changed start_block, an added chain or an upgraded envio can't apply to the existing data. A listed version means the envio version changed.

Solution: Pick one of the printed options. To re-index from scratch, run pnpm envio dev -r locally or envio start -r in production. To keep the old data, start a second indexer with a different ENVIO_PG_SCHEMA and ENVIO_INDEXER_PORT, as option 3 shows. Locally, also see running a second indexer.

Indexer not starting at the specified start block​

Problem: The indexer runs but doesn't start from the start_block defined in your configuration.

Cause: The indexer resumes from the state persisted by a previous run. With HyperSync and start_block: 0, it also skips ahead to the first block with events for your contracts.

Solution: Re-index from scratch:

pnpm envio dev -r

HyperSync API token errors​

  • An Envio API token is required for using HyperSync as a data-source. - set ENVIO_API_TOKEN in your .env file or environment. Get a token at envio.dev/app/api-tokens.
  • Your ENVIO_API_TOKEN was rejected by HyperSync (401 Unauthorized). - the token is invalid or revoked. The indexer keeps retrying, but it reads the token only at startup: update ENVIO_API_TOKEN and restart.
  • HyperSync source is rate-limited - not critical, the indexer will retry in <n>s. - the indexer waits and continues. A token on a higher plan raises the limit.

Tables for entities are not registered on Hasura​

Problem: Entity tables defined in your schema don't appear in Hasura.

Cause: Database schema might be out of sync with your entity definitions.

Solution: Re-index from scratch, which recreates the tables and tracks them in Hasura again:

pnpm envio dev -r

Tables are not tracked when ENVIO_HASURA=false.

Problem: The indexer shows warnings such as:

  • The RPC provider's own error, for example JSON-RPC error -32005: ..., logged with toBlock and retry fields
  • No new blocks detected within <n>s. Polling will continue at a reduced rate.
  • RPC (<host>) is still catching up to block <n>.
  • An error ending in No source available to this chain has served this query on any attempt since, so indexing has stopped making progress.

Cause: Issues connecting to or retrieving data from the blockchain RPC endpoint.

Solutions:

  1. Recommended: Use HyperSync if your chain is supported, as it provides better performance and reliability

  2. If HyperSync isn't an option, try:

    • Using a different RPC endpoint in your config.yaml
    • Verifying your RPC endpoint is stable and has archive data if needed
    • Checking if your RPC provider has rate limits you're exceeding
    • Trying another provider, such as Envio's RPC partner Dwellir
# Example of updating the RPC in config.yaml
chains:
  - id: 1
    start_block: 0
    # Replace with a more reliable RPC
    rpc: "https://mainnet.infura.io/v3/YOUR-API-KEY"

Debugging a Stuck Indexer​

Indexer not making progress​

Problem: Your indexer appears frozen - the block counter stops advancing, or sync has been running far longer than expected with no visible progress.

First step - check the logs:

The most important thing to do is check your indexer logs for errors or warnings. Logs will almost always point you to the root cause.

  • Locally: Check the terminal output from pnpm dev for error messages or stack traces.
  • Envio Cloud: Go to your deployment in the Envio Cloud dashboard and open the Logs tab.

If the logs don't reveal an obvious error, work through the common causes below:

  1. RPC rate limiting or connectivity issues

    • If using RPC sync, your provider may be throttling requests. Check your RPC provider's dashboard for 429 errors or usage spikes.
    • Try switching to a different RPC endpoint or using HyperSync if your chain is supported.

  2. Large blocks or high event density

    • Some blocks contain an unusually large number of events (e.g., airdrop blocks, protocol launches). The indexer may appear stuck while processing them.
    • Check the logs for the current block number - if it's advancing slowly rather than frozen, the indexer is likely processing a dense block range.

  3. Handler errors causing silent failures

    • An unhandled error in your event handler can cause the indexer to stall. Look for error messages or stack traces in the logs that point to a specific handler or event.

  4. Memory pressure

    • Processing very large datasets or having expensive handler logic (e.g., many eth_call requests) can cause memory issues. See the performance optimization guide for tuning options.

If running on Envio Cloud:

  • Check the deployment logs in the Envio Cloud dashboard for error details.
  • If the deployment is unrecoverable, you can delete it and redeploy from the dashboard.
  • Consider running the same configuration locally first to reproduce and debug the issue before redeploying.

Rate Limiting on Hosted Service​

HTTP 429 errors when querying your endpoint​

Problem: You receive 429 Too Many Requests responses when querying your hosted GraphQL endpoint, or your queries are being throttled.

Cause: Envio Cloud applies rate limits to GraphQL query endpoints based on your plan tier. This protects shared infrastructure and ensures fair usage across all deployments.

What to check:

  1. Confirm it's a query rate limit (not an RPC issue)

    • Rate limiting applies to your GraphQL query endpoint, not to the indexer's data ingestion. If your indexer is slow to sync, that's a different issue - see Debugging a Stuck Indexer.

  2. Check your plan's limits

  3. Reduce query frequency from your application

    • If your frontend or backend polls the endpoint frequently, consider adding caching, reducing poll intervals, or using WebSocket subscriptions for real-time updates instead of polling.

  4. Check for unexpected traffic

    • Ensure your endpoint URL hasn't been shared publicly or isn't being hit by an unintended client. You can restrict access - see the Hosted Service features for endpoint security options.

  5. Upgrade your plan

    • If you consistently hit rate limits, consider upgrading to a higher tier for increased query throughput.

Hasura Authentication​

Cannot log in to the Hasura console​

Problem: You're prompted for an admin secret or password when accessing the Hasura console, and don't know what it is.

Local development:

When running locally with pnpm dev, the default Hasura admin secret is testing. Access the console at http://localhost:8080 and enter testing when prompted.

You can customize this by setting the HASURA_GRAPHQL_ADMIN_SECRET environment variable before starting your indexer.

Envio Cloud (hosted):

On Envio Cloud, you do not need the Hasura admin secret to query your data. Your deployed indexer exposes a public GraphQL endpoint that you can query directly without authentication:

https://indexer.dev.hyperindex.xyz/<your-deployment-id>/v1/graphql

The Hasura console UI is not exposed on hosted deployments. To explore your data, use the GraphQL playground available in the Envio Cloud dashboard, or query the endpoint directly from your application or tools like Postman.

If you need to restrict access to your endpoint, see the Hosted Service features for security options.

Infrastructure Conflicts​

Docker or Podman not running​

Problem: pnpm dev fails with Docker or Podman is installed but isn't running, so envio can't start Postgres and Hasura. or Neither Docker nor Podman is installed.

Solution: Start Docker Desktop or the Docker daemon (sudo systemctl start docker on Linux), or install Docker or Podman. On macOS, if Docker runs but isn't found, set export DOCKER_HOST=unix://$HOME/.docker/run/docker.sock. Podman is found through CONTAINER_HOST or its default sockets. To use a Postgres you run yourself, set ENVIO_PG_HOST.

Postgres running locally​

Problem: Starting your indexer fails with Cannot start container envio-postgres. and Port 5433 is already in use.

Cause: Envio publishes its envio-postgres container on host port 5433 by default, not the standard 5432. Something else already holds 5433, such as a Docker Compose stack or a Postgres you started on that port. Other envio dev projects don't clash: they all share the one envio-postgres container.

A Postgres you run yourself on 5432 will not clash with Envio, because Envio does not bind 5432 on the host.

Solution: Stop whatever holds 5433, or point Envio at a free port with ENVIO_PG_PORT:

# Option 1: Set the variable inline
ENVIO_PG_PORT=5434 pnpm dev

# Option 2: Export it for the session, or add it to .env
export ENVIO_PG_PORT=5434
pnpm dev

ENVIO_PG_PORT changes the host port only. Inside the container Postgres still listens on 5432, so anything connecting through Envio needs no change. Changing it, or ENVIO_PG_USER, ENVIO_PG_PASSWORD or ENVIO_PG_DATABASE, recreates the shared envio-postgres container, so use the same values in every project.

Running a second indexer locally: don't change ENVIO_PG_PORT. Give the second project its own schema and metrics port, so both use the shared container side by side:

ENVIO_PG_SCHEMA=second_indexer ENVIO_INDEXER_PORT=9899 pnpm dev

They also share one Hasura, and an indexer that sets up a fresh schema replaces Hasura's table tracking with its own. Add ENVIO_HASURA=false to the second indexer to keep the first one's GraphQL API.

Missing Events​

Events not appearing in indexed data​

Problem: Some expected events are missing from your indexed data, or event counts don't match what you see on-chain.

Common causes:

  1. Incorrect start_block

    • If your start_block is set after the block where the event was emitted, it will be missed. Verify that the start block in your config.yaml is at or before the contract's deployment block.

  2. ABI mismatch

    • If the ABI in your config doesn't match the contract's actual event signature, events won't be decoded. Double-check that your ABI file is up to date and matches the deployed contract.

  3. Missing contract address

    • For multi-address or dynamic contract setups, ensure all relevant addresses are registered. If using dynamic contracts, verify that the contractRegister handler is correctly adding addresses.

  4. RPC provider issues

    • Some RPC providers may return incomplete log data, especially for older blocks. Try switching to a different RPC endpoint or use HyperSync for more reliable data retrieval.

  5. Reorg handling

    • During chain reorganizations, events from orphaned blocks may temporarily appear and then be removed. If rollback_on_reorg is enabled (default), the indexer will handle this automatically. See Reorg Support.

  6. indexed keywords in the event signature don't match the contract

    • HyperIndex matches a log to your event by its signature hash (the first topic) and by its number of topics, which is one more than the number of indexed parameters. If the indexed keywords in the event signature in config.yaml differ from the deployed contract, the logs don't match and are skipped without an error. Copy the signature from the contract source or ABI, with every indexed keyword.

  7. Anonymous events

    • A Solidity event declared anonymous doesn't put its signature hash in the first topic. HyperIndex finds an event's logs by that hash, so anonymous events are not indexed.

How to verify:

  • Check the indexer logs for any skipped blocks or error messages
  • Test with a small block range locally to isolate the issue