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.
Table of Contents
Setup and Configuration Issues
Cannot find module errors on pnpm start
Problem: Errors like Cannot find module
when starting your indexer indicate missing generated files.
Cause: The indexer cannot find necessary files, typically because the code generation step was skipped after cloning the repository.
Solution:
- Delete the
generated
folder if it exists - Run the code generation command:
pnpm codegen
Important: Always run
pnpm codegen
immediately after cloning an indexer repository using Envio.
Smart contract updated after the initial codegen
Problem: Changes to smart contracts aren't reflected in your indexer.
Cause: When smart contracts are modified after initial setup, the ABIs need to be regenerated and the indexer needs to be updated.
Solution:
- Re-export smart contract ABIs (example using Hardhat):
cd contracts/
pnpm hardhat export-abi
- Verify that the ABI directory in
config.yaml
points to the correct location where ABIs were freshly generated - Run codegen again:
pnpm codegen
Using the correct version of Node.js
Problem: Compatibility issues or unexpected errors when running the indexer.
Solution: Envio requires Node.js v18 or newer. If you're using Node.js v16 or older, please update:
# Using nvm (recommended)
nvm install 18
nvm use 18
# Or download directly from https://nodejs.org/
Using the correct version of PNPM
Problem: Package management issues or build failures.
Solution: Envio requires pnpm v8 or newer. If you're using v7.8 or older, please update:
# Update pnpm
npm install -g pnpm@latest
# Verify version
pnpm --version
Runtime Issues
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: This typically happens when the indexer's state is persisted from a previous run.
Solution: Stop the indexer completely before restarting:
# First stop the indexer
pnpm envio stop
# Then restart it
pnpm dev
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: Reset the indexer environment to recreate the necessary tables:
# Stop the indexer
pnpm envio stop
# Restart it (this will recreate tables)
pnpm dev
RPC-Related issues
Problem: The indexer shows warnings such as:
Error getting events, will retry after backoff time
Failed Combined Query Filter from block
Issue while running fetching batch of events from the RPC. Will wait ()ms and try again.
Cause: Issues connecting to or retrieving data from the blockchain RPC endpoint.
Solutions:
-
Recommended: Use HyperSync if your network is supported, as it provides better performance and reliability
-
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
- Using a different RPC endpoint in your
# Example of updating RPC in config.yaml
network:
# Replace with a more reliable RPC
rpc_url: "https://mainnet.infura.io/v3/YOUR-API-KEY"
Infrastructure Conflicts
Postgres running locally
Problem: Conflicts when Postgres is already running on port 5432.
Cause: The default Postgres port (5432) is already in use by another instance.
Solution: Configure Envio to use a different port by setting environment variables:
# Option 1: Set variables inline
ENVIO_PG_PORT=5433 pnpm codegen
ENVIO_PG_PORT=5433 pnpm dev
# Option 2: Export variables for the session
export ENVIO_PG_PORT=5433
pnpm codegen
pnpm dev
You can further customize your Postgres connection with these additional environment variables:
ENVIO_POSTGRES_PASSWORD
: Set a custom passwordENVIO_PG_USER
: Set a custom usernameENVIO_PG_DATABASE
: Set a custom database name