Only custom servers can pass `webpack`, `turbo`, or `turbopa

Error message

Only custom servers can pass `webpack`, `turbo`, or `turbopack`.

What it means

Thrown by createServer() when the server is NOT a custom server (options.customServer is falsy) yet the caller passed `webpack`, `turbo`, or `turbopack` options. These bundler-selection options are only meaningful for custom servers; the standard NextServer (next start/dev) selects the bundler via CLI flags instead.

Source

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

    const selectTurbopack =
      options &&
      (options.turbo || options.turbopack || process.env.IS_TURBOPACK_TEST)
    const selectWebpack =
      options && (options.webpack || process.env.IS_WEBPACK_TEST)
    // Rspack is selected through env/config side effects instead of a custom
    // server option, so don't fall back to the default Turbopack auto mode.
    const selectRspack = !!process.env.NEXT_RSPACK
    if (selectTurbopack && selectWebpack && selectRspack) {
      throw new Error('Pass either `webpack` or `turbopack`, not both.')
    }
    if (selectTurbopack) {
      process.env.TURBOPACK ??= '1'
    } else if (!selectWebpack && !selectRspack) {
      process.env.TURBOPACK ??= 'auto'
    }
  } else {
    if (options && (options.webpack || options.turbo || options.turbopack)) {
      throw new Error(
        'Only custom servers can pass `webpack`, `turbo`, or `turbopack`.'
      )
    }
  }

  // The package is used as a TypeScript plugin.
  if (
    options &&
    'typescript' in options &&
    'version' in (options as any).typescript
  ) {
    const pluginMod: typeof import('./next-typescript') =
      require('./next-typescript') as typeof import('./next-typescript')
    return pluginMod.createTSPlugin(
      options as any
    ) as unknown as NextWrapperServer
  }

View on GitHub (pinned to 0ae8c72462)

Solutions

Remove the `webpack`, `turbo`, and `turbopack` keys from the options object when not using a custom server.
If you need bundler selection in the standard server, use CLI flags (`next dev --turbopack`, `next dev --webpack`) instead.
Set `customServer: true` if you genuinely are running a custom server and need these options.

Example fix

// before
const app = next({ dev, customServer: false, turbopack: true })
// after
const app = next({ dev })

Defensive patterns

Strategy: validation

Validate before calling

const opts = { dev, customServer: false }
if ('webpack' in opts || 'turbo' in opts || 'turbopack' in opts) {
  throw new Error('Bundler options require customServer: true')
}
const app = next(opts)

Prevention

Don't pass webpack/turbo/turbopack to the standard NextServer (non-custom-server).
Use CLI flags (--turbopack/--webpack) for bundler selection in the standard server.
Set customServer: true only when you genuinely run a custom server.

When it happens

Trigger: Calling `next({ customServer: false, turbopack: true })` or programmatically constructing NextServer with bundler keys while not running a custom server.

Common situations: Mistakenly passing bundler options to the default Next() factory expecting CLI-style usage; adapting a custom-server example into a standard setup without removing the bundler keys.

Related errors

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