{"record":{"id":"fafa05bacd6d57d8","repo":"Stirling-Tools/Stirling-PDF","slug":"ssl-tls-certificate-error-server-may-have-an-inva","errorCode":null,"errorMessage":"SSL/TLS certificate error. Server may have an invalid or self-signed certificate.","messagePattern":"SSL/TLS certificate error\\. Server may have an invalid or self-signed certificate\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"frontend/editor/src/desktop/services/authService.ts","lineNumber":466,"sourceCode":"          errMsg.includes(\"dns\") ||\n          errMsg.includes(\"not found\") ||\n          errMsg.includes(\"enotfound\")\n        ) {\n          this.setAuthStatus(\"unauthenticated\", null);\n          throw new Error(\n            \"Cannot resolve server address. Please check the server URL is correct.\",\n            { cause: error },\n          );\n        }\n        // SSL/TLS errors\n        else if (\n          errMsg.includes(\"ssl\") ||\n          errMsg.includes(\"tls\") ||\n          errMsg.includes(\"certificate\") ||\n          errMsg.includes(\"cert\")\n        ) {\n          this.setAuthStatus(\"unauthenticated\", null);\n          throw new Error(\n            \"SSL/TLS certificate error. Server may have an invalid or self-signed certificate.\",\n            {\n              cause: error,\n            },\n          );\n        }\n        // 404 - endpoint not found\n        else if (errMsg.includes(\"404\") || errMsg.includes(\"not found\")) {\n          this.setAuthStatus(\"unauthenticated\", null);\n          throw new Error(\n            \"Login endpoint not found. Please ensure you are connecting to a valid Stirling PDF server.\",\n            {\n              cause: error,\n            },\n          );\n        }\n        // 403 - security disabled\n        else if (errMsg.includes(\"403\") || errMsg.includes(\"forbidden\")) {","sourceCodeStart":448,"sourceCodeEnd":484,"githubUrl":"https://github.com/Stirling-Tools/Stirling-PDF/blob/9ef20dcab80b85041912f045e17a6aea1d08f969/frontend/editor/src/desktop/services/authService.ts#L448-L484","documentation":"Thrown when the login error message contains 'ssl', 'tls', 'certificate', or 'cert'. The TLS handshake failed — typically an untrusted/self-signed certificate, an expired cert, a hostname mismatch, or a missing intermediate CA. Original error preserved as cause; auth resets to unauthenticated.","triggerScenarios":"Server presented a self-signed or expired TLS certificate; cert CN/SAN does not match the hostname in the URL; the desktop's trust store lacks the signing CA; TLS version mismatch (e.g. server TLS 1.0 only).","commonSituations":"Self-hosted Stirling behind a self-signed reverse-proxy cert that is not installed as a trusted root; expired Let's Encrypt cert the admin forgot to renew; corporate MITM proxy with its own CA not trusted by the desktop OS.","solutions":["Install a trusted certificate on the server (Let's Encrypt or a CA the desktop trusts).","If using a private CA, install that CA's root certificate into the desktop OS trust store (macOS Keychain, Windows cert store, Linux ca-certificates).","Verify the cert hostname matches the server URL host (no IP-vs-cert-mismatch).","Renew the cert if it has expired."],"exampleFix":"// before: self-signed cert rejected by desktop trust store\n//   https://stirling.local  -> SSL/TLS certificate error\n// after: install the server's root CA on the desktop, then\nawait authService.login('https://stirling.local', user, pass);","handlingStrategy":"validation","validationCode":"// require https for production servers and warn on suspicious certs up front\nconst u = new URL(serverUrl);\nif (u.protocol !== 'https:') { warn('This server uses HTTP — credentials will be sent unencrypted.'); }","typeGuard":"function isTlsError(e: unknown): e is Error {\n  return e instanceof Error && /SSL\\/TLS certificate error/.test(e.message);\n}","tryCatchPattern":"try { await authService.login(serverUrl, user, pass); }\ncatch (e) {\n  if (isTlsError(e)) { show('The server certificate is untrusted. Install its root CA or use a trusted cert.'); return; }\n  throw e;\n}","preventionTips":["Install the server's root CA into the OS trust store for private CAs.","Prefer Let's Encrypt or a public CA for self-hosted servers.","Never instruct users to globally disable certificate validation."],"tags":["network","tls","ssl","certificate","desktop"],"backgroundTag":null,"analyzedSha":"9ef20dcab80b85041912f045e17a6aea1d08f969","analyzedAt":"2026-08-13T22:11:39.827Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}