Can't exclude datastore from engine function without adapter

Error message

Can't exclude datastore from engine function without adapter providing deployURL

What it means

A Gatsby deployment adapter may exclude the datastore from the serverless engine function (to shrink bundle size), but only when it also provides a deployURL where the datastore can be fetched at runtime. Returning excludeDatastoreFromEngineFunction=true without a deployURL is contradictory and the manager throws.

Source

Thrown at packages/gatsby/src/utils/adapter/manager.ts:263

        },
        reporter,
        // Our internal Gatsby config allows this to be undefined but for the adapter we should always pass through the default values and correctly show this in the TypeScript types
        trailingSlash: trailingSlash as TrailingSlash,
        pathPrefix: pathPrefix as string,
      }

      await adapter.adapt(adaptContext)
    },
    config: async (): Promise<IAdapterFinalConfig> => {
      let configFromAdapter: undefined | IAdapterConfig = undefined
      if (adapter.config) {
        configFromAdapter = await adapter.config({ reporter })

        if (
          configFromAdapter?.excludeDatastoreFromEngineFunction &&
          !configFromAdapter?.deployURL
        ) {
          throw new Error(
            `Can't exclude datastore from engine function without adapter providing deployURL`
          )
        }

        if (configFromAdapter?.imageCDNUrlGeneratorModulePath) {
          global.__GATSBY.imageCDNUrlGeneratorModulePath =
            configFromAdapter.imageCDNUrlGeneratorModulePath
        }

        if (configFromAdapter?.fileCDNUrlGeneratorModulePath) {
          global.__GATSBY.fileCDNUrlGeneratorModulePath =
            configFromAdapter.fileCDNUrlGeneratorModulePath
        }
      }

      return {
        excludeDatastoreFromEngineFunction:
          configFromAdapter?.excludeDatastoreFromEngineFunction ?? false,

View on GitHub (pinned to 8b06340921)

Solutions

Set deployURL alongside excludeDatastoreFromEngineFunction: true.
If you have no deployURL, set excludeDatastoreFromEngineFunction: false (or omit it).
Verify the adapter's config() returns both fields together when excluding the datastore.

Example fix

// before
async config() {
  return { excludeDatastoreFromEngineFunction: true }
}
// after
async config() {
  return {
    excludeDatastoreFromEngineFunction: true,
    deployURL: process.env.DEPLOY_URL,
  }
}

Defensive patterns

Strategy: validation

Validate before calling

function validateAdapterConfig(cfg) {
  if (cfg?.excludeDatastoreFromEngineFunction && !cfg?.deployURL) {
    throw new Error('excludeDatastoreFromEngineFunction requires deployURL')
  }
}

Type guard

function adapterConfigIsConsistent(cfg) {
  return !cfg?.excludeDatastoreFromEngineFunction || Boolean(cfg?.deployURL)
}

Prevention

Always pair excludeDatastoreFromEngineFunction with a concrete deployURL in adapter config().
Add an integration test that asserts the adapter returns both fields together.
Read deployURL from a guaranteed-present env var when excluding the datastore.

When it happens

Trigger: A custom adapter's config() returns { excludeDatastoreFromEngineFunction: true } but no deployURL string.

Common situations: Authoring/testing a custom Gatsby adapter (e.g. for a non-Gatsby-Cloud target); forking an adapter and removing the deployURL; misordered adapter config.

Related errors

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