> For the complete documentation index, see [llms.txt](https://docs.envio.dev/llms.txt).

# 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](https://discord.gg/envio) for additional support.

For build, deployment and access problems on Envio Cloud, see [Envio Cloud Troubleshooting](https://docs.envio.dev/docs/HyperIndex/envio-cloud-troubleshooting.md).

## Table of Contents

- [Setup and Configuration Issues](#setup-and-configuration-issues)
  - [Module Not Found Errors](#cannot-find-module-errors-on-pnpm-start)
  - [Config Parsing Errors](#config-parsing-errors)
  - [Non-interactive `envio init`](#non-interactive-envio-init-fails)
  - [ES Module Errors](#es-module-errors-on-start)
  - [Smart Contract Updates](#smart-contract-updated-after-the-initial-codegen)
  - [Struct (Tuple) Event Parameters](#events-with-struct-tuple-parameters)
  - [Node.js Version Compatibility](#using-the-correct-version-of-nodejs)
- [Runtime Issues](#runtime-issues)
  - [Incompatible Config Changes](#config-changes-are-incompatible-with-the-existing-indexer-data)
  - [Indexer Start Block Issues](#indexer-not-starting-at-the-specified-start-block)
  - [HyperSync API Token Errors](#hypersync-api-token-errors)
  - [Tables Not Registered in Hasura](#tables-for-entities-are-not-registered-on-hasura)
  - [RPC-Related Issues](#rpc-related-issues)
- [Debugging a Stuck Indexer](#debugging-a-stuck-indexer)
  - [Indexer Not Making Progress](#indexer-not-making-progress)
- [Rate Limiting on Hosted Service](#rate-limiting-on-hosted-service)
  - [HTTP 429 Errors](#http-429-errors-when-querying-your-endpoint)
- [Hasura Authentication](#hasura-authentication)
  - [Cannot Log In to the Hasura Console](#cannot-log-in-to-the-hasura-console)
- [Infrastructure Conflicts](#infrastructure-conflicts)
  - [Docker Not Running](#docker-or-podman-not-running)
  - [Local Postgres Conflicts](#postgres-running-locally)
- [Missing Events](#missing-events)
  - [Events Not Appearing in Indexed Data](#events-not-appearing-in-indexed-data)

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

```bash
pnpm codegen
```

3. If the error names `generated`, import from `"envio"` instead. V3 has no `generated` package; see [Migrate to V3](https://docs.envio.dev/docs/HyperIndex/migrate-to-v3.md#step-6-update-handler-code).

> **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:

```yaml
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](#es-module-errors-on-start).

### 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 u64` | Use the numeric chain ID, not a chain name. Check `${VAR}` values too. |
| `The RPC url "wss://..." is incorrect format` | `url` must be `http(s)://`. Put a WebSocket URL in the [`ws` field](/docs/HyperIndex/configuration-file#websocket-height-streaming). |
| `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 sync` | Remove 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`](/docs/HyperIndex/cli-commands#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:

```json
{
  "type": "module"
}
```

In a monorepo, the `package.json` that counts is the nearest one above your handler files. See [Migrate to V3](https://docs.envio.dev/docs/HyperIndex/migrate-to-v3.md#step-2-update-packagejson) 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):

```bash
cd contracts/
pnpm hardhat export-abi
```

2. Verify that the ABI directory in `config.yaml` points to the correct location where ABIs were freshly generated
3. Run codegen again:

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

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

```ts
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:

```bash
# 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](#postgres-running-locally).

### 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:

```bash
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](https://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:

```bash
pnpm envio dev -r
```

Tables are not tracked when `ENVIO_HASURA=false`.

### RPC-Related issues

**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](https://docs.envio.dev/docs/HyperIndex/hypersync.md) 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](https://www.dwellir.com/networks?utm_source=envio.dev)

```yaml
# 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](https://envio.dev/app) 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](https://docs.envio.dev/docs/HyperIndex/hypersync.md) 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](https://docs.envio.dev/docs/HyperIndex/performance.md) for tuning options.

**If running on Envio Cloud:**

- Check the deployment logs in the [Envio Cloud dashboard](https://envio.dev/app) 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](#debugging-a-stuck-indexer).

2. **Check your plan's limits**
   - Review your current plan in the [Envio Cloud dashboard](https://envio.dev/app) under your deployment settings. Higher-tier plans include higher query rate limits. See [Billing & Plans](https://docs.envio.dev/docs/HyperIndex/hosted-service-billing.md) for details.

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](https://docs.envio.dev/docs/HyperIndex/websockets.md) 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](https://docs.envio.dev/docs/HyperIndex/hosted-service-features.md) 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](https://envio.dev/app), 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](https://docs.envio.dev/docs/HyperIndex/hosted-service-features.md) 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`:

```bash
# 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:

```bash
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](https://docs.envio.dev/docs/HyperIndex/dynamic-contracts.md), 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](https://docs.envio.dev/docs/HyperIndex/hypersync.md) 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](https://docs.envio.dev/docs/HyperIndex/reorgs-support.md).

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

---