GraphQL Code Generator "Failed to load schema ... ECONNREFUSED" in CI

By Daniel Zoghalchali·Latchkey

When the schema pointer is a URL, GraphQL Code Generator introspects it over HTTP. ECONNREFUSED means nothing was listening at that address from the runner: the API is not started, the host is unreachable, or the port is wrong.

What this error means

graphql-codegen fails with "Failed to load schema from http://localhost:4000/graphql: connect ECONNREFUSED 127.0.0.1:4000". Public schema files would not hit the network at all.

Failed to load schema from http://localhost:4000/graphql:
        connect ECONNREFUSED 127.0.0.1:4000

Common causes

The GraphQL server is not running in CI

codegen points at a localhost URL but no server was started before the generate step, so the connection is refused.

Wrong host or port for the runner

A URL that works locally (localhost) is not reachable as written from inside a container or service network in CI.

How to fix it

Start the API or wait for it before codegen

1. Start the GraphQL server (or a service container) before the generate step.
2. Wait until the endpoint accepts connections.
3. Run codegen against the now-reachable URL.

- run: npm run start:api &
- run: npx wait-on http://localhost:4000/graphql
- run: npx graphql-codegen

Use a committed schema file instead of a URL

Avoid the network entirely by introspecting once and committing SDL or introspection JSON the job reads.

# codegen.yml
schema: ./schema.graphql

How to prevent it

• Prefer a committed schema file over a live URL in CI codegen.
• If a URL is required, start the server and wait for readiness first.
• Use service-network hostnames, not localhost, inside containers.

Frequently asked questions

Related guides

References

• GitHub Actions documentation