What causes "GraphQL request returned an empty string." in gatsbyjs/gatsby?

Curl the GraphQL endpoint with the same query: curl -X POST -H 'Content-Type: application/json' -d '{"query":"{generalSettings{url}}"}' and inspect the raw body.

gatsbyjs/gatsby · error

GraphQL request returned an empty string.

Error message

GraphQL request returned an empty string.

What it means

After the retry loop completes, fetch-graphql checks that response.data is not an empty string. WPGraphQL should always return a JSON body; an empty body indicates the endpoint returned nothing (server crash, proxy interception, wrong URL returning a 200 with empty body). This is distinct from a network error (which the retry/bail handles) — the HTTP call succeeded but produced no data.

Source

Thrown at packages/gatsby-source-wordpress/src/utils/fetch-graphql.ts:768

        moduleHelpers
          .getHttp(limit)
          .post(url, { query, variables }, requestOptions)
          .catch(e => {
            if (!errorIs500ish(e)) {
              // for any error that is not a 50x error, we bail, meaning we stop retrying. error will be thrown one level higher
              bail(e)

              return null
            } else {
              // otherwise throwing the error will cause the retry to happen again
              throw e
            }
          }),
      { retries: 5 }
    )

    if (response.data === ``) {
      throw new Error(`GraphQL request returned an empty string.`)
    }

    const { path }: { path: string } = urlUtil.parse(url)

    const responsePath = response.request.path

    if (
      path !== responsePath &&
      responsePath !== undefined &&
      responsePath !== url
    ) {
      throw new Error(`GraphQL request was redirected to ${responsePath}`)
    }

    const contentType: string = response.headers[`content-type`]

    if (!contentType.includes(`application/json;`)) {
      throw new Error(`Unable to connect to WPGraphQL.`)

View on GitHub (pinned to 8b06340921)

Solutions

Curl the GraphQL endpoint with the same query: curl -X POST <url> -H 'Content-Type: application/json' -d '{"query":"{generalSettings{url}}"}' and inspect the raw body.
Confirm WPGraphQL (and WPGatsby) are activated on the WordPress side.
Verify pluginOptions.url points to the GraphQL endpoint (typically /graphql), not the site root.
Check PHP error logs on the WordPress server for fatal errors during the request.

Example fix

// before
url: `https://wp.example.com`

// after
url: `https://wp.example.com/graphql`

Defensive patterns

Strategy: try-catch

Validate before calling

const probe = await axios.post(url, { query: '{generalSettings{url}}' })
if (probe.data === '') { throw new Error('Endpoint returned empty body; check WPGraphQL activation and url') }

Type guard

null

Try / catch

try { await fetchGraphQL(opts) } catch (e) { if (/empty string/.test(e.message)) { reporter.panic('WPGraphQL returned an empty body; verify url and plugin activation') } throw e }

Prevention

Probe the GraphQL endpoint with curl before running the build
Confirm WPGraphQL and WPGatsby are activated
Set the correct /graphql path in pluginOptions.url
Monitor PHP error logs for fatal errors

When it happens

Trigger: WPGraphQL endpoint URL points to a plain page that returns an empty 200; PHP fatal error before WPGraphQL runs, returning empty body; a caching layer returning an empty cached response; URL is correct host but wrong path.

Common situations: WPGraphQL plugin not activated (server returns the WP homepage HTML, but here the empty-string branch fires when the body is literally empty); reverse proxy stripping the body; misconfigured url in pluginOptions; server-side fatal during the GraphQL request.

Related errors

AI-assisted analysis of gatsbyjs/gatsby@8b06340921 (2026-08-13). Data as JSON: /api/errors/562b00031c3fa71c. Report an issue: GitHub.