nextauthjs/next-auth · warning

env-url-basepath-mismatch

env-url-basepath-mismatch

Error message

env-url-basepath-mismatch

What it means

createActionURL builds action URLs from AUTH_URL (envUrl) when present. If both AUTH_URL's pathname and the configured basePath exist and differ, the library warns 'env-url-basepath-mismatch' and resets url.pathname to '/' so the basePath from config wins. It indicates your environment URL and route prefix disagree, which can break redirects and callback URLs.

Source

Thrown at packages/core/src/lib/utils/env.ts:89

}

export function createActionURL(
  action: AuthAction,
  protocol: string,
  headers: Headers,
  envObject: any,
  config: Pick<AuthConfig, "basePath" | "logger">
): URL {
  const basePath = config?.basePath
  const envUrl = envObject.AUTH_URL ?? envObject.NEXTAUTH_URL

  let url: URL
  if (envUrl) {
    url = new URL(envUrl)
    if (basePath && basePath !== "/" && url.pathname !== "/") {
      if (url.pathname !== basePath) {
        const logger = setLogger(config)
        logger.warn("env-url-basepath-mismatch")
      }
      url.pathname = "/"
    }
  } else {
    const detectedHost = headers.get("x-forwarded-host") ?? headers.get("host")
    const detectedProtocol =
      headers.get("x-forwarded-proto") ?? protocol ?? "https"
    const _protocol = detectedProtocol.endsWith(":")
      ? detectedProtocol
      : detectedProtocol + ":"

    url = new URL(`${_protocol}//${detectedHost}`)
  }

  // remove trailing slash
  const sanitizedUrl = url.toString().replace(/\/$/, "")

  if (basePath) {

View on GitHub (pinned to a1a16a5a77)

Solutions

1. Set AUTH_URL so its pathname equals config.basePath (or has no path at all)
2. Remove the basePath from AUTH_URL (use bare origin) and rely on config.basePath only
3. Ensure the build-time env (e.g. NEXTAUTH_URL/AUTH_URL baked at build) matches the runtime deployment
4. Filter logger.warn for this code if the mismatch is known and intentional

Example fix

// before
AUTH_URL=https://app.example.com/legacy-auth
basePath: '/api/auth'
// after
AUTH_URL=https://app.example.com/api/auth
basePath: '/api/auth'

const envPath = new URL(process.env.AUTH_URL).pathname
if (envPath !== '/' && envPath !== basePath) {
  console.error(`AUTH_URL path ${envPath} mismatches basePath ${basePath}`)
}

function envUrlMatchesBasePath(u: string, basePath: string): boolean {
  try { const p = new URL(u).pathname; return p === '/' || p === basePath } catch { return false }
}

When it happens

Trigger: Calling createActionURL (via url, signInURL, sessionUrl) when process.env.AUTH_URL has a non-'/' pathname that is not equal to config.basePath, e.g. AUTH_URL=https://x.com/other and basePath '/api/auth'.

Common situations: Deploy previews or proxies injecting a different AUTH_URL; copying AUTH_URL between services that use different route prefixes; forgetting to update AUTH_URL after renaming the auth route; monorepos where one app overrides AUTH_URL.

Related errors

• env-url-basepath-redundant
• Dgraph client error: Please provide an API key
• Dgraph client error: Please provide a valid GraphQL endpoint
• csrf-disabled
• Unsupported database type (${typeof db}) in Auth.js Drizzle

AI-assisted analysis of nextauthjs/next-auth@a1a16a5a77 (2026-08-28). Data as JSON: /api/errors/f626f261ee7558a3. Report an issue: GitHub.