{"record":{"id":"10909bfa181542f9","repo":"gethomepage/homepage","slug":"homepage-external-url-or-nextauth-url-must-be-an","errorCode":null,"errorMessage":"HOMEPAGE_EXTERNAL_URL (or NEXTAUTH_URL) must be an absolute HTTP(S) URL.","messagePattern":"HOMEPAGE_EXTERNAL_URL \\(or NEXTAUTH_URL\\) must be an absolute HTTP\\(S\\) URL\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"src/pages/api/auth/[...nextauth].js","lineNumber":44,"sourceCode":"if (!process.env.NEXTAUTH_URL && homepageExternalUrl) {\n  process.env.NEXTAUTH_URL = homepageExternalUrl;\n}\n\nconst defaultScope = process.env.HOMEPAGE_OIDC_SCOPE || \"openid email profile\";\nconst cleanedIssuer = issuer ? issuer.replace(/\\/+$/, \"\") : issuer;\nconst hasOidcConfig = Boolean(issuer && clientId && clientSecret);\nconst hasAnyOidcConfig = Boolean(issuer || clientId || clientSecret);\nlet parsedAuthUrl;\n\nif (authEnabled) {\n  if (!process.env.NEXTAUTH_URL) {\n    throw new Error(\"Homepage auth is enabled but HOMEPAGE_EXTERNAL_URL (or NEXTAUTH_URL) is missing.\");\n  }\n\n  try {\n    parsedAuthUrl = new URL(process.env.NEXTAUTH_URL);\n  } catch {\n    throw new Error(\"HOMEPAGE_EXTERNAL_URL (or NEXTAUTH_URL) must be an absolute HTTP(S) URL.\");\n  }\n\n  if (\n    ![\"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    }","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/gethomepage/homepage/blob/b6dca1ae033e613d8e692f9a161a3cc53a5a2857/src/pages/api/auth/[...nextauth].js#L26-L62","documentation":"Thrown when NEXTAUTH_URL / HOMEPAGE_EXTERNAL_URL is present but `new URL(...)` rejects it, meaning the value is not a parseable absolute URL. Homepage refuses to proceed because NextAuth needs a valid absolute URL for redirects and JWT signing.","triggerScenarios":"authEnabled is true, NEXTAUTH_URL is truthy, but its value cannot be parsed by the WHATWG URL constructor (e.g. 'home.example.com', 'home', '//home', 'ftp x', or an empty-ish malformed string). The `catch {}` block around `new URL(...)` re-throws this message.","commonSituations":"User omitted the scheme (wrote 'home.example.com' instead of 'https://home.example.com'); trailing copy-paste introduced a space; value bound to a wrong env var; Docker env interpolation produced an empty/garbage string.","solutions":["Set the URL with an explicit https:// (or http://) scheme and a host: https://home.example.com.","Check for leading/trailing whitespace or quotes in the env value, especially in docker-compose / Kubernetes secrets.","Verify the variable actually feeding NEXTAUTH_URL/HOMEPAGE_EXTERNAL_URL — print it once in a debug shell inside the container.","If testing locally without TLS, use http://127.0.0.1:3000 (still must be absolute)."],"exampleFix":"// before\nHOMEPAGE_EXTERNAL_URL=home.example.com\n\n// after\nHOMEPAGE_EXTERNAL_URL=https://home.example.com","handlingStrategy":"validation","validationCode":"function assertAbsoluteUrl(raw, name = 'URL') {\n  let u;\n  try { u = new URL(raw); } catch { throw new Error(`${name} is not a valid absolute URL: ${raw}`); }\n  return u;\n}\n// before app boot:\nif (process.env.HOMEPAGE_AUTH_ENABLED === 'true') {\n  assertAbsoluteUrl(process.env.NEXTAUTH_URL || process.env.HOMEPAGE_EXTERNAL_URL, 'NEXTAUTH_URL');\n}","typeGuard":"function isValidAbsoluteUrl(v) {\n  if (typeof v !== 'string' || !v.trim()) return false;\n  try { new URL(v); return true; } catch { return false; }\n}","tryCatchPattern":null,"preventionTips":["Always include the scheme (https://) when setting URL env.","Lint env files for scheme-less URLs.","Use a docker compose `${VAR:?error}` assertion to fail at container start.","Document the expected URL shape next to the variable in your env template."],"tags":["auth","configuration","env","validation","url"],"backgroundTag":null,"analyzedSha":"b6dca1ae033e613d8e692f9a161a3cc53a5a2857","analyzedAt":"2026-08-13T04:48:44.121Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}