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

Envio Cloud Troubleshooting

Answers to the most common problems when deploying and running indexers on Envio Cloud. For issues with running your indexer locally, see Common Issues.

Why does my indexer build locally but fail on Envio Cloud?​

First, make sure your deployment meets the requirements.

Envio Cloud builds from the commit on GitHub and only uploads the folder set as Indexer Directory in your indexer settings. Check the following:

  • Imports outside the indexer directory: code imported from a folder above the Indexer Directory is not uploaded. Move shared code inside the Indexer Directory, or set the Indexer Directory to a folder that contains everything the indexer imports.
  • Files that are not committed: anything in .gitignore or not pushed to the deployment branch is not part of the build.
  • Skipped folders and files: folders named generated or node_modules are skipped at any depth, as are dotfiles other than .npmrc and dot folders other than .envio. Skipped files are left out without an error, so the build only fails later, for example with a missing file or import. Keep files the indexer needs, such as ABIs, in a folder with a different name, and set environment variables in the Environment Variables tab rather than a .env file.
  • Envio version: envio must be listed in the package.json inside the Indexer Directory with an exact version, such as "envio": "x.y.z", that meets the version requirements. Values such as ~x.y.z, latest or workspace:* are rejected, and the commit shows "Invalid version" with the message "The Envio version is not supported".
  • Dependency versions: Envio Cloud resolves dependencies on every build and does not use your pnpm-lock.yaml, so a version range can resolve to a newer release than the one you run locally. Pin exact versions if the build differs from your local setup.

Why didn't my push start a deployment?​

Check the commit's status first, in Recent Commits or with envio-cloud indexer commits <indexer> -o json. The commit statuses table explains each one.

  • Branch name: the branch you pushed to must match Git Release Branch in your indexer settings exactly, including case.
  • Automatic deployments: check that Automatically Deploy On Push is enabled in your indexer settings. When it is disabled, deploy a commit from the Recent Commits section instead.
  • Member role: pushes from members with the reader role do not start a deployment automatically. An admin can deploy the commit from Recent Commits.
  • Deployment limit: each indexer can have 3 deployments. Delete an old deployment, then deploy the commit from Recent Commits. See Deployment Limits.
  • Paused indexer: pushes to a paused indexer do not start a deployment. See Why is my indexer paused?
  • Indexer Directory or Config File: if either path is wrong, the commit shows "Failed to download" or "Missing config". The Config File path is relative to the Indexer Directory. After changing the Indexer Directory, push a new commit.
  • Repository access: the Envio Deployments GitHub App must have access to the repository. Add it in the app's settings on GitHub.
  • Renamed GitHub organisation: Envio Cloud identifies your organisation by its GitHub name, so pushes stop starting deployments after the organisation is renamed. Renaming is not handled automatically, so contact us before renaming an organisation that has indexers on Envio Cloud, or as soon as possible if you already have.

Why did my deployment fail with "Failed to apply schema"?​

The build succeeded, but the database could not be set up from your schema. Open the logs for the deployment and read the lines above "Failed to apply schema", which contain the specific error. Check the build logs first, then the runtime logs. In the CLI, the build logs need the --build flag:

envio-cloud deployment logs <indexer> <commit> [organisation] --build
envio-cloud deployment logs <indexer> <commit> [organisation]

See Deployment Logs in the CLI documentation.

  • If the error refers to your schema.graphql, fix the schema and push a new commit.
  • If the error does not relate to your schema, contact us with the deployment link.

Why does codegen fail on Envio Cloud?​

Codegen runs on every build with the envio version from your package.json. To reproduce the failure, install the same version locally and run:

pnpm envio codegen

Check that config.yaml and schema.graphql are valid and that every file they reference is inside the Indexer Directory, committed and not in a skipped folder, for example an ABI inside a folder named generated. The build logs show the error codegen reported.

Why didn't deploying an older commit start a deployment?​

Deploying a commit from Recent Commits, or with envio-cloud deployment deploy, can be accepted without a new deployment appearing, for example when the commit's code is no longer available after you deleted its deployment. Push a new commit to the branch set as Git Release Branch instead. An empty commit works:

git commit --allow-empty -m "Redeploy"
git push

If a new commit also does not deploy, check Why didn't my push start a deployment?

Why did my build time out?​

Builds that run for longer than about 30 minutes are stopped. Check the build logs for the step that was running when the build stopped. If it keeps timing out, contact us with the deployment link.

Why can't I see my organisation or repository in Envio Cloud?​

Installing the GitHub App adds the person who installed it. Other members of the GitHub organisation must be added by an organisation admin on the Members page before they can see the organisation, its repositories and indexers. Until then they see "You are not a member of this team". See Access Control.

Only people who are members of the GitHub organisation can be added.

How do I add someone to my organisation?​

An organisation admin can select Add next to the person on the Members page. The page lists the members of your GitHub organisation, so the person must be a member there first. See Adding Members.

How do I remove someone from my organisation?​

An organisation admin can select Disable next to the member on the Members page. The member loses access to the organisation in Envio Cloud. Admins can enable them again while they are still a member of the GitHub organisation.

Why is my indexer paused?​

An indexer is most often paused because of outstanding payments. Settle your account, then contact the Envio team to resume indexing. Indexers on the development plan are also scaled down when they pass the fair usage limits.