gatsbyjs/gatsby · error

WPGraphQL returned a debug message on startup

Error message

WPGraphQL returned a debug message on startup:

${firstError.debugMessage || firstError.message}

What it means

blankGetRequest does a bare GET on the WordPress URL and inspects the JSON body for GraphQL errors on startup. If the first error carries a debugMessage or a message other than the benign 'must include query or queryId' one, it panics — meaning WPGraphQL itself reported an error on the site before sourcing began.

Solutions

  1. Fix the WPGraphQL startup problem reported in the debug message on the WordPress side (often a conflicting plugin or PHP error).
  2. Enable WP_DEBUG on the WordPress site to get more detail, resolve the issue, then rebuild.
Defensive patterns

Strategy: try-catch

When it happens

Trigger: Thrown at packages/gatsby-source-wordpress/src/steps/check-plugin-requirements.ts:217 when the library encounters an invalid state.

Common situations: Occurs when WPGraphQL emits a debug message at startup, usually because WPGraphQL debug mode is enabled or another plugin conflicts. Disable WPGraphQL debug mode in production and resolve the reported message.

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

Appendix: source

Thrown at packages/gatsby-source-wordpress/src/steps/check-plugin-requirements.ts:217

  helpers,
}: {
  url: string
  helpers: NodePluginArgs
}): Promise<void> =>
  fetch(url)
    .then(response => response.json())
    .then(json => {
      if (json?.errors?.length) {
        const firstError = json.errors[0]

        if (
          firstError.debugMessage ||
          (firstError.message &&
            !firstError.message?.includes(
              `GraphQL Request must include at least one of those two parameters: "query" or "queryId"`
            ))
        ) {
          helpers.reporter.panic(
            formatLogMessage(`WPGraphQL returned a debug message on startup:

${firstError.debugMessage || firstError.message}
          `)
          )
        }
      }
    })
    .catch(() => {
      // this is ignored because a /graphql request will always return a 200 at this point
      // we've already checked prior to this point that /graphql is up and returns a response.
    })

const isWpGatsby = async (): Promise<void> => {
  fetchGraphql({
    query: /* GraphQL */ `
      {
        isWpGatsby

View on GitHub (pinned to 8b06340921)