{"record":{"id":"62a75d588aea73e9","repo":"decolua/9router","slug":"certificate-install-failed-error-message","errorCode":null,"errorMessage":"Certificate install failed: ${error.message}","messagePattern":"Certificate install failed: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/mitm/cert/install.js","lineNumber":245,"sourceCode":"  if (!isSudoAvailable()) {\n    log(`🔐 Cert: cannot install to system store without sudo — trust this file on clients: ${certPath}`);\n    // Still try to update user NSS DBs even if no sudo!\n    await updateNssDatabases(certPath, 'add');\n    return;\n  }\n  \n  const config = getLinuxCertConfig();\n  const destFile = `${config.dir}/9router-root-ca.crt`;\n  \n  // Copy to the discovered directory and execute the specific update command\n  const cmd = `cp \"${certPath}\" \"${destFile}\" && (${config.cmd} 2>/dev/null || true)`;\n  \n  try {\n    await execWithPassword(cmd, sudoPassword);\n    await updateNssDatabases(certPath, 'add');\n    log(`🔐 Cert: ✅ installed to Linux trust store (${config.dir}) and user browser databases`);\n  } catch (error) {\n    throw new Error(`Certificate install failed: ${error.message}`);\n  }\n}\n\nasync function uninstallCertLinux(sudoPassword) {\n  // Always try to uninstall from user DBs even without sudo\n  await updateNssDatabases(null, 'delete');\n\n  if (!isSudoAvailable()) {\n    return;\n  }\n  \n  const config = getLinuxCertConfig();\n  const destFile = `${config.dir}/9router-root-ca.crt`;\n  const cmd = `rm -f \"${destFile}\" && (${config.cmd} 2>/dev/null || true)`;\n  \n  try {\n    await execWithPassword(cmd, sudoPassword);\n    log(\"🔐 Cert: ✅ uninstalled from Linux trust store and user browser databases\");","sourceCodeStart":227,"sourceCodeEnd":263,"githubUrl":"https://github.com/decolua/9router/blob/90b52e06ffd666b7929554211474d01588f6b1f8/src/mitm/cert/install.js#L227-L263","documentation":"installCertLinux() copies the CA into the distro trust directory and updates NSS browser databases (updateNssDatabases 'add') via sudo. Any failure of execWithPassword or the NSS update is rethrown as `Certificate install failed: <detail>`.","triggerScenarios":"installCert() on Linux when: the sudo password is wrong, the trust command for the distro (update-ca-certificates / update-ca-trust) fails, the target trust dir doesn't match the detected distro config, or certutil (NSS) is missing/unable to open the browser profile databases.","commonSituations":"Unsupported/minimal distro where getLinuxCertConfig() guessed the wrong dir; Firefox/NSS DB locked while the browser is running; certutil not installed (libnss3-tools missing); sudo requiring TTY in headless sessions.","solutions":["Install NSS tools (`apt install libnss3-tools` / `dnf install nss-tools`) so browser DB updates can run","Close Firefox/Chrome before installing so the NSS databases are not locked","Verify the sudo password is correct (`sudo -v`)","Manually copy the CA to the distro trust dir and run update-ca-certificates to see the raw error","Check getLinuxCertConfig() detected the right distro family"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Ensure prerequisites before install\nawait exec('command -v certutil || echo NSS_TOOLS_MISSING');\nif (!fs.existsSync(certPath)) throw new Error('cert file missing before Linux install');","typeGuard":null,"tryCatchPattern":"try {\n  await installCert(sudoPassword, certPath);\n} catch (e) {\n  if (e.message.startsWith('Certificate install failed:')) {\n    console.error('Linux trust install failed:', e.message);\n    // suggest: install libnss3-tools, close browsers, retry\n  } else throw e;\n}","preventionTips":["Install libnss3-tools/nss-tools as a documented prerequisite","Ask users to close Firefox/Chromium before install to avoid locked NSS DBs","Verify sudo works non-interactively before triggering install"],"tags":["linux","certificate","sudo","nss"],"backgroundTag":"certificate-install-failed","analyzedSha":"90b52e06ffd666b7929554211474d01588f6b1f8","analyzedAt":"2026-08-30T21:05:45.952Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}