Config options `experimental.proxyPrefetch` and `experimenta

Error message

Config options `experimental.proxyPrefetch` and `experimental.middlewarePrefetch` cannot be set at the same time. Please use `experimental.proxyPrefetch` instead.

What it means

Same aliasing pattern as the body-size option: `experimental.middlewarePrefetch` was renamed to `experimental.proxyPrefetch`. The guard at config.ts:980-987 forbids both being set explicitly because the later alias-mapping code would conflict. Use only the new proxy-prefixed key.

Source

Thrown at packages/next/src/server/config.ts:984

        'Server Actions Size Limit must be a valid number or filesize format larger than 1MB: https://nextjs.org/docs/app/api-reference/next-config-js/serverActions#bodysizelimit'
      )
    }
  }

  // Throw if both Middleware and Proxy config are set.
  if (
    userConfig.experimental?.proxyClientMaxBodySize !== undefined &&
    userConfig.experimental?.middlewareClientMaxBodySize !== undefined
  ) {
    throw new Error(
      'Config options `experimental.proxyClientMaxBodySize` and `experimental.middlewareClientMaxBodySize` cannot be set at the same time. Please use `experimental.proxyClientMaxBodySize` instead.'
    )
  }
  if (
    userConfig.experimental?.proxyPrefetch !== undefined &&
    userConfig.experimental?.middlewarePrefetch !== undefined
  ) {
    throw new Error(
      'Config options `experimental.proxyPrefetch` and `experimental.middlewarePrefetch` cannot be set at the same time. Please use `experimental.proxyPrefetch` instead.'
    )
  }
  if (
    userConfig.experimental?.externalProxyRewritesResolve !== undefined &&
    userConfig.experimental?.externalMiddlewareRewritesResolve !== undefined
  ) {
    throw new Error(
      'Config options `experimental.externalProxyRewritesResolve` and `experimental.externalMiddlewareRewritesResolve` cannot be set at the same time. Please use `experimental.externalProxyRewritesResolve` instead.'
    )
  }
  if (
    userConfig.skipProxyUrlNormalize !== undefined &&
    userConfig.skipMiddlewareUrlNormalize !== undefined
  ) {
    throw new Error(
      'Config options `skipProxyUrlNormalize` and `skipMiddlewareUrlNormalize` cannot be set at the same time. Please use `skipProxyUrlNormalize` instead.'
    )

View on GitHub (pinned to 0ae8c72462)

Solutions

Delete `experimental.middlewarePrefetch` and keep `experimental.proxyPrefetch`.
Verify the prefetch behavior you intend (proxy prefetch controls preloading of routes through the proxy layer).
Grep the config for any other `middleware*` keys to finish the migration.

Example fix

// before
module.exports = { experimental: { proxyPrefetch: true, middlewarePrefetch: true } }
// after
module.exports = { experimental: { proxyPrefetch: true } }

Defensive patterns

Strategy: validation

Validate before calling

const e = config.experimental ?? {};
if (e.proxyPrefetch !== undefined && e.middlewarePrefetch !== undefined) {
  throw new Error('set only experimental.proxyPrefetch');
}

Prevention

Treat any `middleware*` experimental key as deprecated; prefer the `proxy*` alias.
Add an ESLint custom rule or config schema validator to flag both keys present.

When it happens

Trigger: Setting both `experimental.proxyPrefetch` and `experimental.middlewarePrefetch` in the same config.

Common situations: Partial config migration during a Next.js upgrade. Merging two config files where one used the old name.

Related errors

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