gatsbyjs/gatsby · error

SyncError

SyncError

Error message

Fetching contentful data failed: ${createContentfulErrorMessage(e)}

What it means

handleContentfulError rethrows a fatal panic after the Contentful SDK's fetch of sync data fails. The message wraps the SDK error plus actionable context: suggests GATSBY_CONTENTFUL_OFFLINE=true to serve from cache and echoes the resolved plugin options used, so credential/endpoint problems can be spotted.

Solutions

1. Check network connectivity to the Contentful API (cdn.contentful.com).
2. Verify the space ID and access token are correct and the token is not expired or revoked.
3. Retry the build; intermittent Contentful API errors often resolve on retry.

When it happens

Trigger: Thrown at packages/gatsby-source-contentful/src/fetch.js:323 when the library encounters an invalid state.

Common situations: Occurs when fetching entries/assets from Contentful fails mid-sync, often due to rate limits, network interruptions, or revoked tokens. Retry the build, verify the access token, and consider lowering request concurrency.

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

Appendix: source

Thrown at packages/gatsby-source-contentful/src/fetch.js:323

          currentPageLimit = Math.floor((currentPageLimit / 3) * 2) || 1
          reporter.warn(
            [
              `The sync with Contentful failed using pageLimit ${lastCurrentPageLimit} as the reponse size limit of the API is exceeded.`,
              `Retrying sync with pageLimit of ${currentPageLimit}`,
            ].join(`\n\n`)
          )
          continue
        }
        throw e
      }
      if (currentPageLimit !== pageLimit) {
        reporter.warn(
          `We recommend you to set your pageLimit in gatsby-config.js to ${currentPageLimit} to avoid failed synchronizations.`
        )
      }
    }
  } catch (e) {
    reporter.panic({
      id: CODES.SyncError,
      context: {
        sourceMessage: `Fetching contentful data failed: ${createContentfulErrorMessage(
          e
        )}`,
      },
    })
  } finally {
    // Fix output when there was no new data in Contentful
    if (
      !currentSyncData?.entries.length &&
      !currentSyncData?.assets.length &&
      !currentSyncData?.deletedEntries.length &&
      !currentSyncData?.deletedAssets.length
    ) {
      syncProgress.tick()
      syncProgress.total = 1
    }

View on GitHub (pinned to 8b06340921)