gatsbyjs/gatsby · error

We recommend you to set your pageLimit in gatsby-config.js t

Error message

We recommend you to set your pageLimit in gatsby-config.js to ${currentPageLimit} to avoid failed synchronizations.

What it means

This warning fires in fetchContent's error handler when a Contentful initial sync fails with 'Response size too big' and the current pageLimit is above 1. The plugin automatically shrinks the sync page size to two-thirds (floor((limit/3)*2), min 1) and retries, so the warning is advisory: it tells the user to hard-code the reduced limit in gatsby-config.js so future syncs succeed on the first attempt.

Source

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

          e.response?.data?.message.includes(`Response size too big`) &&
          currentPageLimit > 1
        ) {
          lastCurrentPageLimit = currentPageLimit
          // Reduce page limit by a arbitrary 1/3 of the current limit to ensure
          // the new and bigger entries are synced without exceeding the reponse size limit
          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 &&

View on GitHub (pinned to e85d62f177)

Solutions

1. Set the pageLimit option in gatsby-config.js to the value suggested in the warning (the reduced limit) so syncs no longer exceed the API response size limit.
2. Keep pageLimit at 1 if a single entry is already too large, or reduce the size of very large entries in Contentful.
3. Re-run the build; the plugin retries the sync automatically with the smaller page limit.

When it happens

Trigger: Thrown at packages/gatsby-source-contentful/src/fetch.js:317 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/efc966cffe6f7925. Report an issue: GitHub.