{"record":{"id":"3270bce88fdd87a5","repo":"louislam/uptime-kuma","slug":"failed-to-read-envname-file-at-filevalue","errorCode":null,"errorMessage":"Failed to read ${envName}_FILE at ${fileValue}: ${err.message}","messagePattern":"Failed to read (.+?)_FILE at (.+?): (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"server/setup-database.js","lineNumber":31,"sourceCode":" * Reads a configuration value from an environment variable or a Docker secrets file.\n * If both the direct env var and the _FILE variant are set, an error is thrown.\n * @param {string} envName The base name of the environment variable (e.g., \"UPTIME_KUMA_DB_PASSWORD\")\n * @returns {string|undefined} The value from the env var, file contents (trimmed), or undefined if neither is set\n * @throws {Error} If both the direct env var and the _FILE variant are set\n */\nfunction getEnvOrFile(envName) {\n    const directValue = process.env[envName];\n    const fileValue = process.env[envName + \"_FILE\"];\n\n    if (directValue && fileValue) {\n        throw new Error(`Both ${envName} and ${envName}_FILE are set. Please use only one.`);\n    }\n\n    if (fileValue) {\n        try {\n            return fs.readFileSync(fileValue, \"utf8\").trim();\n        } catch (err) {\n            throw new Error(`Failed to read ${envName}_FILE at ${fileValue}: ${err.message}`);\n        }\n    }\n\n    return directValue;\n}\n\n/**\n *  A standalone express app that is used to setup a database\n *  It is used when db-config.json and kuma.db are not found or invalid\n *  Once it is configured, it will shut down and start the main server\n */\nclass SetupDatabase {\n    /**\n     * Show Setup Page\n     * @type {boolean}\n     */\n    needSetup = true;\n    /**","sourceCodeStart":13,"sourceCodeEnd":49,"githubUrl":"https://github.com/louislam/uptime-kuma/blob/6b5ea0155793e666666745fb8d6fef1e829543a2/server/setup-database.js#L13-L49","documentation":"Thrown by getEnvOrFile(envName) when the *_FILE path is set but fs.readFileSync fails (the secrets file does not exist, is unreadable, or wrong permissions). The original fs error message is appended for diagnosis.","triggerScenarios":"UPTIME_KUMA_DB_*_FILE points at a path that the process cannot open: secret not mounted in the container, file removed, path typo, or restrictive file mode. Triggered during setup-database bootstrap.","commonSituations":"Docker secret named differently than the path; Kubernetes secret not mounted because the deployment spec references a missing secret; running as a uid without read permission on the secrets file; bind-mount path differs between host and container.","solutions":["Verify the file exists inside the container at the exact *_FILE path (docker exec ls -l /run/secrets/<name>).","Fix the secret name/mount so the file is present and readable by the kuma process uid.","Correct the *_FILE environment value to the real path, or unset it and use the direct variable instead."],"exampleFix":"# before\nUPTIME_KUMA_DB_PASSWORD_FILE=/run/secrets/db_pass\n# (file not mounted)\n# after\nvolumes:\n  - db_password_secret:/run/secrets/db_password:ro\nUPTIME_KUMA_DB_PASSWORD_FILE=/run/secrets/db_password","handlingStrategy":"validation","validationCode":"// Pre-flight: ensure secret files are readable\nconst fs = require(\"fs\");\nfunction assertSecretReadable(fileEnv) {\n  const p = process.env[fileEnv];\n  if (p && !fs.existsSync(p)) {\n    throw new Error(`${fileEnv} -> ${p} missing; mount the secret.`);\n  }\n}\nassertSecretReadable(\"UPTIME_KUMA_DB_PASSWORD_FILE\");","typeGuard":"function secretFileOk(fileEnv) {\n  const p = process.env[fileEnv];\n  return !p || (fs.existsSync(p) && fs.accessSync.bind(fs, p, fs.constants.R_OK) || true);\n}","tryCatchPattern":"try {\n  boot();\n} catch (e) {\n  if (/Failed to read .*_FILE at/.test(e.message)) {\n    haltWithHint(\"Secret file path unreadable: \" + e.message);\n  } else throw e;\n}","preventionTips":["Verify secret mounts with docker exec ls -l before starting.","Run the kuma container as a uid that can read /run/secrets.","Keep *_FILE paths consistent across environments."],"tags":["config","docker-secrets","filesystem","startup","database"],"backgroundTag":null,"analyzedSha":"6b5ea0155793e666666745fb8d6fef1e829543a2","analyzedAt":"2026-08-12T23:42:12.959Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}