{"record":{"id":"6eb1aba5f549ca38","repo":"gethomepage/homepage","slug":"password-auth-is-enabled-but-required-settings-are","errorCode":null,"errorMessage":"Password auth is enabled but required settings are missing.","messagePattern":"Password auth is enabled but required settings are missing\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"src/pages/api/auth/[...nextauth].js","lineNumber":66,"sourceCode":"    ![\"http:\", \"https:\"].includes(parsedAuthUrl.protocol) ||\n    parsedAuthUrl.username ||\n    parsedAuthUrl.password ||\n    parsedAuthUrl.search ||\n    parsedAuthUrl.hash\n  ) {\n    throw new Error(\n      \"HOMEPAGE_EXTERNAL_URL (or NEXTAUTH_URL) must be an absolute HTTP(S) URL without credentials, query, or fragment.\",\n    );\n  }\n\n  if (hasOidcConfig) {\n    if (!process.env.NEXTAUTH_SECRET) {\n      throw new Error(\"OIDC auth is enabled but required settings are missing.\");\n    }\n  } else if (hasAnyOidcConfig) {\n    throw new Error(\"OIDC auth is enabled but required settings are missing.\");\n  } else if (!homepageAuthPassword || !process.env.NEXTAUTH_SECRET) {\n    throw new Error(\"Password auth is enabled but required settings are missing.\");\n  }\n\n  if (process.env.NEXTAUTH_SECRET.length < MIN_AUTH_SECRET_LENGTH) {\n    throw new Error(\n      `HOMEPAGE_AUTH_SECRET (or NEXTAUTH_SECRET) must be at least ${MIN_AUTH_SECRET_LENGTH} characters. Generate one with: openssl rand -base64 32`,\n    );\n  }\n}\n\n// Give fail2ban / CrowdSec etc something to match on\nfunction logFailedPasswordSignIn() {\n  createLogger(\"nextauth\").warn(\"Failed password sign-in attempt\");\n}\n\nlet providers = [];\nif (authEnabled) {\n  if (hasOidcConfig) {\n    providers = [","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/gethomepage/homepage/blob/b6dca1ae033e613d8e692f9a161a3cc53a5a2857/src/pages/api/auth/[...nextauth].js#L48-L84","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","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."],"exampleFix":"// before\nHOMEPAGE_AUTH_ENABLED=true\n# password and/or secret missing\n\n// after\nHOMEPAGE_AUTH_ENABLED=true\nHOMEPAGE_AUTH_PASSWORD=correct-horse-battery-staple\nNEXTAUTH_SECRET=$(openssl rand -base64 32)","handlingStrategy":"validation","validationCode":"function validatePasswordAuth(env) {\n  const oidc = env.HOMEPAGE_OIDC_ISSUER || env.HOMEPAGE_OIDC_CLIENT_ID || env.HOMEPAGE_OIDC_CLIENT_SECRET;\n  if (oidc) return; // OIDC path\n  if (!env.HOMEPAGE_AUTH_PASSWORD || !env.NEXTAUTH_SECRET) {\n    throw new Error('Password auth requires both HOMEPAGE_AUTH_PASSWORD and NEXTAUTH_SECRET');\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["auth","password","configuration","env","secret","startup"],"backgroundTag":null,"analyzedSha":"b6dca1ae033e613d8e692f9a161a3cc53a5a2857","analyzedAt":"2026-08-13T04:48:44.121Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}