gatsbyjs/gatsby · error

Unable to connect to WPGraphQL.

Error message

Unable to connect to WPGraphQL.

What it means

fetch-graphql checks that the response Content-Type includes 'application/json;'. WPGraphQL always returns JSON; any other content type (text/html from a 404 page, an XML error, a plain-text proxy message) means the endpoint did not handle the request as GraphQL. This usually indicates the URL is wrong, WPGraphQL is disabled, or a server-side error page is being served.

Source

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

      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.`)
    }
  } catch (e) {
    if (throwFetchErrors) {
      throw e
    }

    await handleFetchErrors({
      e,
      reporter,
      url,
      timeout,
      variables,
      pluginOptions,
      query,
      response,
      errorContext,
      isFirstRequest,
    })

View on GitHub (pinned to 8b06340921)

Solutions

1. Confirm WPGraphQL is installed and activated on the WordPress site.
2. Verify pluginOptions.url resolves to the GraphQL endpoint (visit it in a browser; you should see GraphiQL or a JSON error, not a webpage).
3. Check PHP error logs for fatal errors during GraphQL requests.
4. Ensure the web server (nginx/apache) rewrite rules forward /graphql to index.php for WPGraphQL.

Example fix

null

const probe = await axios.post(url, { query: '{generalSettings{url}}' })
if (!probe.headers['content-type']?.includes('application/json')) { throw new Error('Endpoint did not return JSON; verify WPGraphQL is active and url is correct') }

null

try { await fetchGraphQL(opts) } catch (e) { if (/Unable to connect to WPGraphQL/.test(e.message)) { reporter.panic('WPGraphQL not reachable; check url and plugin activation') } throw e }

When it happens

Trigger: URL points to a non-GraphQL page (HTML returned); WPGraphQL plugin disabled; PHP error producing an HTML error page; web server returning XML for a 404; maintenance mode returning an HTML splash page.

Common situations: Wrong url (pointing to the site root or a page); WPGraphQL/WPGatsby deactivated on the WordPress instance; server-side PHP error rendering HTML; web server rewrite rules not routing /graphql to WPGraphQL.

Related errors

• GraphQL request returned an empty string.
• GraphQL request was redirected to ${responsePath}
• BabelPluginRemoveGraphQLQueries: the "${exportName}" export
• Source GraphQL API: HTTP error ${response.status} ${response
• stringifiedErrors

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