gatsbyjs/gatsby · error

[gatsby-adapter-netlify] excludeDatastoreFromEngineFunction

Error message

[gatsby-adapter-netlify] excludeDatastoreFromEngineFunction is set to true but no DEPLOY_URL is set. Disabling excludeDatastoreFromEngineFunction.

What it means

Degrade-to-safe-default warning in createNetlifyAdapter: excludeDatastoreFromEngineFunction was enabled (via plugin option or GATSBY_EXCLUDE_DATASTORE_FROM_BUNDLE) and the adapter wanted to copy the datastore to Netlify's CDN by fetching the deploy URL, but no DEPLOY_URL/NETLIFY_LOCAL equivalent was present in the environment. Since the datastore can only be excluded when its download URL is known, the adapter logs this notice and silently disables the optimization (falls back to bundling the datastore in the function).

Source

Thrown at packages/gatsby-adapter-netlify/src/index.ts:154

      if (
        typeof excludeDatastoreFromEngineFunction === `undefined` &&
        typeof process.env.GATSBY_EXCLUDE_DATASTORE_FROM_BUNDLE !== `undefined`
      ) {
        excludeDatastoreFromEngineFunction =
          process.env.GATSBY_EXCLUDE_DATASTORE_FROM_BUNDLE === `true` ||
          process.env.GATSBY_EXCLUDE_DATASTORE_FROM_BUNDLE === `1`
      }

      if (typeof excludeDatastoreFromEngineFunction === `undefined`) {
        excludeDatastoreFromEngineFunction = false
      }

      const deployURL = process.env.NETLIFY_LOCAL
        ? `http://localhost:8888`
        : process.env.DEPLOY_URL

      if (excludeDatastoreFromEngineFunction && !deployURL) {
        reporter.warn(
          `[gatsby-adapter-netlify] excludeDatastoreFromEngineFunction is set to true but no DEPLOY_URL is set. Disabling excludeDatastoreFromEngineFunction.`
        )
        excludeDatastoreFromEngineFunction = false
      }

      return {
        excludeDatastoreFromEngineFunction,
        deployURL,
        supports: {
          pathPrefix: true,
          trailingSlash: [`always`, `never`, `ignore`],
        },
        pluginsToDisable: [
          `gatsby-plugin-netlify-cache`,
          `gatsby-plugin-netlify`,
        ],
        imageCDNUrlGeneratorModulePath: useNetlifyImageCDN
          ? require.resolve(`./image-cdn-url-generator`)

View on GitHub (pinned to e85d62f177)

Solutions

1. Ensure the build runs in a real Netlify CI context where DEPLOY_URL (or NETLIFY_LOCAL with the dev server on localhost:8888) is set
2. Set DEPLOY_URL explicitly to the public URL of the deployment if building outside Netlify
3. If the optimization is not needed, leave excludeDatastoreFromEngineFunction unset/false so the warning path is never taken

When it happens

Trigger: Thrown at packages/gatsby-adapter-netlify/src/index.ts:154 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/f3d6ad45a647559c. Report an issue: GitHub.