gatsbyjs/gatsby · critical · Error

Cannot access Contentful space "${maskText(pluginOptions.spa

Error message

Cannot access Contentful space "${maskText(pluginOptions.spaceId)}" on environment "${pluginOptions.environment}" with access token "${maskText(pluginOptions.accessToken)}". Make sure to double check them!

What it means

Thrown by gatsby-source-contentful's validateContentfulAccess when the HTTP request to the Contentful Content Management API returns a non-OK status (4xx/5xx). This means the spaceId, environment, or accessToken is incorrect, or the token lacks permission. Credentials are masked in the message for safety.

Source

Thrown at packages/gatsby-source-contentful/src/gatsby-node.js:39

    {
      headers: {
        Authorization: `Bearer ${pluginOptions.accessToken}`,
        "Content-Type": `application/json`,
      },
    }
  )
    .then(res => res.ok)
    .then(ok => {
      if (!ok) {
        const errorMessage = `Cannot access Contentful space "${maskText(
          pluginOptions.spaceId
        )}" on environment "${
          pluginOptions.environment
        }" with access token "${maskText(
          pluginOptions.accessToken
        )}". Make sure to double check them!`

        throw new Error(errorMessage)
      }
    })

  return undefined
}

export const onPreInit = async (
  { store, reporter, actions },
  pluginOptions
) => {
  // if gatsby-plugin-image is not installed
  try {
    await import(`gatsby-plugin-image/graphql-utils`)
  } catch (err) {
    reporter.panic({
      id: CODES.GatsbyPluginMissing,
      context: {
        sourceMessage: `gatsby-plugin-image is missing from your project.\nPlease install "gatsby-plugin-image".`,

View on GitHub (pinned to 8b06340921)

Solutions

Double-check spaceId, environment, and accessToken in gatsby-config.js against the Contentful dashboard.
Ensure the accessToken has read access to the specified environment (not just master).
Verify the environment name exists in the space (Contentful > Settings > Environments).
Regenerate the access token in Contentful if it may be expired or revoked.
Check for trailing spaces or copy-paste errors in the credentials.

Example fix

// before
{
  resolve: 'gatsby-source-contentful',
  options: {
    spaceId: 'space-id',
    accessToken: 'wrong-token',
    environment: 'master'
  }
}
// after
{
  resolve: 'gatsby-source-contentful',
  options: {
    spaceId: 'correct-space-id',
    accessToken: 'CFPAT-correct-token',
    environment: 'main'
  }
}

Defensive patterns

Strategy: retry

Validate before calling

// Validate Contentful credentials format before build
const { spaceId, accessToken, environment } = pluginOptions
if (!spaceId || !accessToken || !environment) {
  throw new Error('Contentful spaceId, accessToken, and environment are all required')
}
if (!accessToken.startsWith('CDA') && !accessToken.startsWith('CFPAT')) {
  console.warn('Access token format looks unusual — verify it is a Contentful token')
}

Try / catch

try {
  await validateContentfulAccess(pluginOptions)
} catch (e) {
  if (e.message.includes('Cannot access Contentful')) {
    // check credentials, retry with corrected config
  } else throw e
}

Prevention

Store Contentful credentials in environment variables, not in gatsby-config directly.
Verify spaceId, environment, and accessToken in the Contentful dashboard before building.
Ensure the access token has read access to the target environment.
Use a pre-build script to test Contentful API connectivity.

When it happens

Trigger: fetch() to contentful.com returns res.ok === false (HTTP 401/403/404); spaceId, environment, or accessToken in pluginOptions is wrong, expired, or from a different environment.

Common situations: Wrong spaceId copied from Contentful, access token from a different space or environment, token revoked/expired, environment name typo, or network/proxy returning an error page.

Related errors

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