gatsbyjs/gatsby · error

Pretty permalinks are not enabled in your WordPress instance

Error message

Pretty permalinks are not enabled in your WordPress instance.
Gatsby routing requires this setting to function properly.
Please enable pretty permalinks by changing your settings at
${data.generalSettings.url}/wp-admin/options-permalink.php.

What it means

prettyPermalinksAreEnabled queries wpGatsby.arePrettyPermalinksEnabled and the site's URL; the warning fires when WordPress still uses plain (non-pretty) permalinks (e.g. /?p=123). Gatsby's page routing and node relationships rely on clean paths, so requirements checking flags it; the build continues but routing/preview behavior may be broken until permalinks are switched to a pretty structure.

Source

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

  try {
    const { data } = await fetchGraphql({
      query: /* GraphQL */ `
        {
          generalSettings {
            url
          }
          wpGatsby {
            arePrettyPermalinksEnabled
          }
        }
      `,
      throwGqlErrors: true,
      isFirstRequest: true,
    })

    if (!data.wpGatsby.arePrettyPermalinksEnabled) {
      helpers.reporter.log(``)
      helpers.reporter.warn(
        formatLogMessage(`
Pretty permalinks are not enabled in your WordPress instance.
Gatsby routing requires this setting to function properly.
Please enable pretty permalinks by changing your settings at
${data.generalSettings.url}/wp-admin/options-permalink.php.
`)
      )
    }
  } catch (e) {
    // the WPGatsby version is too old to query for wpGatsby.arePrettyPermalinksEnabled
  }
}

const ensurePluginRequirementsAreMet = async (
  helpers: NodePluginArgs
): Promise<void> => {
  if (
    helpers.traceId === `refresh-createSchemaCustomization` ||

View on GitHub (pinned to e85d62f177)

Solutions

1. In WordPress admin go to Settings > Permalinks and select any option other than Plain.
2. Save changes to flush the rewrite rules, then re-run the Gatsby build.
3. Confirm the WPgatsby plugin is active so arePrettyPermalinksEnabled is reported correctly.

When it happens

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

Common situations: See trigger scenarios.

AI-assisted analysis of gatsbyjs/gatsby@e85d62f177 (2026-08-26). Data as JSON: /api/errors/d324015644a87f11. Report an issue: GitHub.