vercel/next.js · error · Error

Draft mode cannot be enabled during build-time instant valid

Error message

Draft mode cannot be enabled during build-time instant validation.

What it means

Thrown by the build-time instant-validation DraftModeProvider.enable() stub. During instant validation, draft mode is intentionally a no-op that always reports disabled; calling enable() is invalid because there is no live request to establish a draft-mode cookie. This prevents components from mutating draft state during static validation.

Source

Thrown at packages/next/src/server/app-render/instant-validation/instant-samples.ts:239

      return Reflect.get(target, prop, receiver)
    },
  })
}

/**
 * Creates a DraftModeProvider that always returns isEnabled: false.
 */
export function createDraftModeForValidation(): DraftModeProvider {
  // Create a minimal DraftModeProvider-compatible object
  // that always reports draft mode as disabled.
  //
  // private properties that can't be set from outside the class.
  return {
    get isEnabled() {
      return false
    },
    enable() {
      throw new Error(
        'Draft mode cannot be enabled during build-time instant validation.'
      )
    },
    disable() {
      throw new Error(
        'Draft mode cannot be disabled during build-time instant validation.'
      )
    },
  } as Partial<DraftModeProvider> as DraftModeProvider
}

/**
 * Creates params wrapped with an exhaustive proxy.
 * Accessing a param not declared in the sample will throw an error.
 */
export function createExhaustiveParamsProxy<TParams extends Params>(
  underlyingParams: TParams,
  declaredParamNames: Set<string>,

View on GitHub (pinned to 0ae8c72462)

Solutions

1. Guard draftMode().enable() so it is not invoked during build/validation -- detect the validation context and skip it.
2. Move draft-mode enablement into a runtime-only route handler that is excluded from instant validation.
3. Conditionally enable draft mode only when a real request/preview token is present.
4. Ensure preview-enabling code lives in an API route excluded from static validation samples.

Example fix

// before
// export default function Handler() { draftMode().enable() }

// after: skip in build/validation context
// if (process.env.NEXT_RUNTIME) draftMode().enable() // runtime only

// Skip draft-mode enablement during build/validation.
function enablePreview() {
  if (process.env.NEXT_PHASE === 'phase-production-build') return
  draftMode().enable()
}

When it happens

Trigger: During instant validation render, application code calls draftMode().enable() (e.g. in a preview/preview-API-like flow). The validation DraftModeProvider.enable() throws immediately.

Common situations: A route handler or component that enables draft mode (e.g. an API route for preview) is exercised during instant validation; shared code unconditionally enables draft mode; enabling preview in build-time validation where no request exists.

Related errors

• Draft mode cannot be disabled during build-time instant vali
• Invalid sample: Defining cookies via a "cookie" header is no
• Expected sample param value for segment '${rawSegment}' to b
• Expected sample param value for segment '${rawSegment}' to b
• Invalid --top value: ${topRaw}

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