{"record":{"id":"f746896d798247db","repo":"gatsbyjs/gatsby","slug":"unable-to-connect-to-wpgraphql","errorCode":null,"errorMessage":"Unable to connect to WPGraphQL.","messagePattern":"Unable to connect to WPGraphQL\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/gatsby-source-wordpress/src/utils/fetch-graphql.ts","lineNumber":786,"sourceCode":"      throw new Error(`GraphQL request returned an empty string.`)\n    }\n\n    const { path }: { path: string } = urlUtil.parse(url)\n\n    const responsePath = response.request.path\n\n    if (\n      path !== responsePath &&\n      responsePath !== undefined &&\n      responsePath !== url\n    ) {\n      throw new Error(`GraphQL request was redirected to ${responsePath}`)\n    }\n\n    const contentType: string = response.headers[`content-type`]\n\n    if (!contentType.includes(`application/json;`)) {\n      throw new Error(`Unable to connect to WPGraphQL.`)\n    }\n  } catch (e) {\n    if (throwFetchErrors) {\n      throw e\n    }\n\n    await handleFetchErrors({\n      e,\n      reporter,\n      url,\n      timeout,\n      variables,\n      pluginOptions,\n      query,\n      response,\n      errorContext,\n      isFirstRequest,\n    })","sourceCodeStart":768,"sourceCodeEnd":804,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/8b06340921ffdf23125a365b9c9923690cb62ce6/packages/gatsby-source-wordpress/src/utils/fetch-graphql.ts#L768-L804","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Confirm WPGraphQL is installed and activated on the WordPress site.","Verify pluginOptions.url resolves to the GraphQL endpoint (visit it in a browser; you should see GraphiQL or a JSON error, not a webpage).","Check PHP error logs for fatal errors during GraphQL requests.","Ensure the web server (nginx/apache) rewrite rules forward /graphql to index.php for WPGraphQL."],"exampleFix":"null","handlingStrategy":"validation","validationCode":"const probe = await axios.post(url, { query: '{generalSettings{url}}' })\nif (!probe.headers['content-type']?.includes('application/json')) { throw new Error('Endpoint did not return JSON; verify WPGraphQL is active and url is correct') }","typeGuard":"null","tryCatchPattern":"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 }","preventionTips":["Visit the GraphQL URL in a browser and confirm GraphiQL or JSON","Keep WPGraphQL and WPGatsby activated","Configure nginx/apache rewrite rules to route /graphql to WPGraphQL","Watch for HTML maintenance pages during deploys"],"tags":["wordpress","graphql","config","network"],"backgroundTag":null,"analyzedSha":"8b06340921ffdf23125a365b9c9923690cb62ce6","analyzedAt":"2026-08-13T02:36:21.405Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}