nextauthjs/next-auth · warning

env-url-basepath-redundant

env-url-basepath-redundant

Error message

env-url-basepath-redundant

What it means

setEnvDefaults derives basePath from AUTH_URL's pathname when config.basePath is unset. If you ALSO set config.basePath manually while AUTH_URL already contains a path, the two sources conflict, so the library logs this warning and keeps the explicit basePath. It means your AUTH_URL pathname is redundant and may diverge from the actual route prefix.

Source

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

import type { AuthConfig } from "../../index.js"
import { setLogger } from "./logger.js"

/**
 *  Set default env variables on the config object
 * @param suppressWarnings intended for framework authors.
 */
export function setEnvDefaults(
  envObject: any,
  config: AuthConfig,
  suppressBasePathWarning = false
) {
  try {
    const url = envObject.AUTH_URL
    if (url) {
      if (config.basePath) {
        if (!suppressBasePathWarning) {
          const logger = setLogger(config)
          logger.warn("env-url-basepath-redundant")
        }
      } else {
        config.basePath = new URL(url).pathname
      }
    }
  } catch {
    // Catching and swallowing potential URL parsing errors, we'll fall
    // back to `/auth` below.
  } finally {
    config.basePath ??= `/auth`
  }

  if (!config.secret?.length) {
    config.secret = []
    const secret = envObject.AUTH_SECRET
    if (secret) config.secret.push(secret)
    for (const i of [1, 2, 3]) {
      const secret = envObject[`AUTH_SECRET_${i}`]

View on GitHub (pinned to a1a16a5a77)

Solutions

1. Remove the path portion from AUTH_URL (use origin only, e.g. https://app.example.com) and keep config.basePath
2. Or remove config.basePath and let setEnvDefaults derive it from AUTH_URL's pathname
3. Keep AUTH_URL and basePath in sync across environments (build-time vs runtime) so they never disagree

Example fix

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

const url = new URL(process.env.AUTH_URL)
if (config.basePath && url.pathname !== '/' && url.pathname !== config.basePath) {
  console.warn('AUTH_URL contains a redundant basePath')
}

function authUrlPathIsRoot(u: string): boolean {
  try { return new URL(u).pathname === '/' } catch { return false }
}

When it happens

Trigger: Calling setEnvDefaults with envObject.AUTH_URL set (e.g. AUTH_URL=https://app.example.com/auth/v1) while config.basePath is also non-empty (e.g. basePath: '/api/auth').

Common situations: Copying deployment URLs that already include the auth path into AUTH_URL while keeping basePath in config; migrating from AUTH_URL-only setups to explicit basePath; environment templates where staging URLs include a subpath.

Related errors

• env-url-basepath-mismatch
• 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/c9dc69a7e3ccb8f9. Report an issue: GitHub.