Apollo "Network error: Failed to fetch" during SSR in CI

By Kaveh Alemi·Latchkey

Apollo's HTTP link calls fetch, and "Failed to fetch" means the request never completed: the endpoint was unreachable, the URL was relative under SSR, or no fetch implementation was available in the CI runtime.

What this error means

An SSR render or integration test fails with "ApolloError: Network error: Failed to fetch" (or "TypeError: Failed to fetch"). It passes in a browser but fails on the headless CI runner.

ApolloError: Network error: Failed to fetch
    at new ApolloError (.../core/ApolloError.js)
  networkError: TypeError: Failed to fetch

Common causes

A relative URI with no origin under SSR

On the server there is no browser origin, so a relative uri: '/graphql' has nothing to resolve against and fetch fails immediately.

The GraphQL server is not reachable from the runner

The endpoint host is wrong, the service container has not started, or the port is not exposed to the job, so the connection cannot be made.

How to fix it

Use an absolute URI and a real fetch on the server

1. Configure HttpLink with an absolute URL that the runner can reach.
2. Provide a server-side fetch (Node 18+ has global fetch; otherwise inject cross-fetch).
3. Wait for the GraphQL service to be healthy before rendering or testing.

import { HttpLink } from '@apollo/client';
const link = new HttpLink({
  uri: process.env.GRAPHQL_URL ?? 'http://localhost:4000/graphql',
});

Gate tests on a health check

Block the test step until the endpoint answers so SSR does not fetch before the server is up.

until curl -fsS http://localhost:4000/graphql -o /dev/null \
  -d '{"query":"{__typename}"}' -H 'content-type: application/json'; do sleep 1; done

How to prevent it

• Always configure an absolute GraphQL URL for SSR and CI.
• Ensure a fetch implementation exists in the server runtime.
• Health-check the GraphQL service before SSR or tests run.

Frequently asked questions

Related guides

References

• GitHub Actions documentation