vercel/next.js · error

prepare() must be called before performing this operation

Error message

prepare() must be called before performing this operation

What it means

Lifecycle invariant on NextCustomServer: an accessor (requestHandler, upgradeHandler, server) that depends on the server's initialization result was touched before prepare() completed. The init field is only populated during prepare, so this indicates a usage-order bug in a custom server integration.

Source

Thrown at packages/next/src/server/next.ts:440

  }
}

/** The wrapper server used for `import next from "next" (in a custom server)` */
class NextCustomServer implements NextWrapperServer {
  private didWebSocketSetup: boolean = false
  protected cleanupListeners?: AsyncCallbackSet

  protected init?: ServerInitResult

  public options: NextServerOptions

  constructor(options: NextServerOptions) {
    this.options = options
  }

  protected getInit() {
    if (!this.init) {
      throw new Error(
        'prepare() must be called before performing this operation'
      )
    }
    return this.init
  }

  protected get requestHandler() {
    return this.getInit().requestHandler
  }
  protected get upgradeHandler() {
    return this.getInit().upgradeHandler
  }
  protected get server() {
    return this.getInit().server
  }

  get hostname() {
    return this.options.hostname

View on GitHub (pinned to 0eb3775416)

Solutions

1. Call await app.prepare() before handling requests with the custom server.

When it happens

Trigger: A server operation is invoked before app.prepare() completed.

Common situations: Calling request handlers on a custom Next.js server before awaiting prepare().

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