gethomepage/homepage · critical · Error

Password auth is enabled but required settings are missing.

Error message

Password auth is enabled but required settings are missing.

What it means

Thrown when neither OIDC nor partial-OIDC is configured (password-auth path) but the password-auth prerequisites are missing: either HOMEPAGE_AUTH_PASSWORD or NEXTAUTH_SECRET (or both) is unset. Homepage needs both a password to check credentials against and a secret to sign the session.

Source

Thrown at src/pages/api/auth/[...nextauth].js:66

    !["http:", "https:"].includes(parsedAuthUrl.protocol) ||
    parsedAuthUrl.username ||
    parsedAuthUrl.password ||
    parsedAuthUrl.search ||
    parsedAuthUrl.hash
  ) {
    throw new Error(
      "HOMEPAGE_EXTERNAL_URL (or NEXTAUTH_URL) must be an absolute HTTP(S) URL without credentials, query, or fragment.",
    );
  }

  if (hasOidcConfig) {
    if (!process.env.NEXTAUTH_SECRET) {
      throw new Error("OIDC auth is enabled but required settings are missing.");
    }
  } else if (hasAnyOidcConfig) {
    throw new Error("OIDC auth is enabled but required settings are missing.");
  } else if (!homepageAuthPassword || !process.env.NEXTAUTH_SECRET) {
    throw new Error("Password auth is enabled but required settings are missing.");
  }

  if (process.env.NEXTAUTH_SECRET.length < MIN_AUTH_SECRET_LENGTH) {
    throw new Error(
      `HOMEPAGE_AUTH_SECRET (or NEXTAUTH_SECRET) must be at least ${MIN_AUTH_SECRET_LENGTH} characters. Generate one with: openssl rand -base64 32`,
    );
  }
}

// Give fail2ban / CrowdSec etc something to match on
function logFailedPasswordSignIn() {
  createLogger("nextauth").warn("Failed password sign-in attempt");
}

let providers = [];
if (authEnabled) {
  if (hasOidcConfig) {
    providers = [

View on GitHub (pinned to b6dca1ae03)

Solutions

Set HOMEPAGE_AUTH_PASSWORD to the password users will sign in with.
Generate and set NEXTAUTH_SECRET (or HOMEPAGE_AUTH_SECRET if your wiring maps it to NEXTAUTH_SECRET) via `openssl rand -base64 32`.
Verify neither value is an empty string — `VAR=` still produces a falsy check here.
Restart the container.

Example fix

// before
HOMEPAGE_AUTH_ENABLED=true
# password and/or secret missing

// after
HOMEPAGE_AUTH_ENABLED=true
HOMEPAGE_AUTH_PASSWORD=correct-horse-battery-staple
NEXTAUTH_SECRET=$(openssl rand -base64 32)

Defensive patterns

Strategy: validation

Validate before calling

function validatePasswordAuth(env) {
  const oidc = env.HOMEPAGE_OIDC_ISSUER || env.HOMEPAGE_OIDC_CLIENT_ID || env.HOMEPAGE_OIDC_CLIENT_SECRET;
  if (oidc) return; // OIDC path
  if (!env.HOMEPAGE_AUTH_PASSWORD || !env.NEXTAUTH_SECRET) {
    throw new Error('Password auth requires both HOMEPAGE_AUTH_PASSWORD and NEXTAUTH_SECRET');
  }
}

Prevention

Document that password auth needs BOTH a password and a JWT secret.
Use a strong generated secret — never reuse the password as the secret.
Add a startup preflight that checks the pair together.
Rotate the password and secret together via your secrets workflow.

When it happens

Trigger: `hasOidcConfig` and `hasAnyOidcConfig` are both false, AND (`!homepageAuthPassword || !process.env.NEXTAUTH_SECRET`). I.e. no OIDC env set at all, and at least one of HOMEPAGE_AUTH_PASSWORD / NEXTAUTH_SECRET missing.

Common situations: Operator enabled auth and set a password but forgot the JWT secret (or vice versa); both were intended to come from a docker secrets mount that failed; env var renamed during an upgrade.

Related errors

AI-assisted analysis of gethomepage/homepage@b6dca1ae03 (2026-08-13). Data as JSON: /api/errors/6eb1aba5f549ca38. Report an issue: GitHub.