vercel/next.js · critical · Error

process.env.NEXT_DEPLOYMENT_ID is missing but runtimeServerD

Error message

process.env.NEXT_DEPLOYMENT_ID is missing but runtimeServerDeploymentId is enabled

What it means

Thrown during NextServer/NextNodeServer construction when the experimental runtimeServerDeploymentId flag is enabled but process.env.NEXT_DEPLOYMENT_ID is not set. The feature requires a deployment id at runtime to stamp assets/routes; its absence is a misconfiguration, so startup aborts.

Source

Thrown at packages/next/src/server/base-server.ts:492

    this.dir = path.resolve(/* turbopackIgnore: true */ dir)

    this.quiet = quiet
    this.loadEnvConfig({ dev, forceReload: false })

    // TODO: should conf be normalized to prevent missing
    // values from causing issues as this can be user provided
    this.nextConfig = conf as NextConfigRuntime
    if (
      (dev || process.env.__NEXT_DEV_SERVER) &&
      this.nextConfig.experimental.requestInsights
    ) {
      process.env.__NEXT_REQUEST_INSIGHTS = 'true'
    }

    if (this.nextConfig.experimental.runtimeServerDeploymentId) {
      if (!process.env.NEXT_DEPLOYMENT_ID) {
        throw new Error(
          'process.env.NEXT_DEPLOYMENT_ID is missing but runtimeServerDeploymentId is enabled'
        )
      }
      this.deploymentId = process.env.NEXT_DEPLOYMENT_ID
    } else {
      let id = this.nextConfig.experimental.useSkewCookie
        ? ''
        : this.nextConfig.deploymentId || ''

      this.deploymentId = id
      process.env.NEXT_DEPLOYMENT_ID = id
    }
    ;(globalThis as any).NEXT_CLIENT_ASSET_SUFFIX =
      this.nextConfig.supportsImmutableAssets || !this.deploymentId
        ? ''
        : `?dpl=${this.deploymentId}`

    this.hostname = hostname

View on GitHub (pinned to 0ae8c72462)

Solutions

Set NEXT_DEPLOYMENT_ID to a stable value in your environment (e.g. a commit sha or release id) before starting the server.
If you do not need the feature, remove experimental.runtimeServerDeploymentId (or set it false) from next.config.js.
Ensure your deploy pipeline injects NEXT_DEPLOYMENT_ID consistently across all instances.
Validate the env var is present in your runtime environment before the server starts.

Example fix

// before
// next.config.js: { experimental: { runtimeServerDeploymentId: true } }
// (NEXT_DEPLOYMENT_ID unset)

// after: provide the env var
// NEXT_DEPLOYMENT_ID=abc123 next start

Defensive patterns

Strategy: validation

Validate before calling

// Fail fast at startup if the required env is missing.
if (require('./next.config.js').experimental?.runtimeServerDeploymentId) {
  if (!process.env.NEXT_DEPLOYMENT_ID) {
    throw new Error('runtimeServerDeploymentId requires NEXT_DEPLOYMENT_ID')
  }
}

Prevention

Always set NEXT_DEPLOYMENT_ID when enabling runtimeServerDeploymentId.
Inject NEXT_DEPLOYMENT_ID from your CI release id/commit sha.
Remove the experimental flag if you don't need it.
Add an env-var check to your deploy script.

When it happens

Trigger: next.config.js sets experimental.runtimeServerDeploymentId = true, but the NEXT_DEPLOYMENT_ID environment variable is unset when the server boots. The constructor (base-server.ts:490-495) checks and throws immediately.

Common situations: Enabling the experimental deployment-id feature without providing the env var; CI/local dev copying a config that expects a platform-provided NEXT_DEPLOYMENT_ID; feature flag left on from a template.

Related errors

AI-assisted analysis of vercel/next.js@0ae8c72462 (2026-08-06). Data as JSON: /api/errors/c577636eeab8d952. Report an issue: GitHub.