Stirling-Tools/Stirling-PDF · error · Error

SSL/TLS certificate error. Server may have an invalid or sel

Error message

SSL/TLS certificate error. Server may have an invalid or self-signed certificate.

What it means

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.

Source

Thrown at frontend/editor/src/desktop/services/authService.ts:466

          errMsg.includes("dns") ||
          errMsg.includes("not found") ||
          errMsg.includes("enotfound")
        ) {
          this.setAuthStatus("unauthenticated", null);
          throw new Error(
            "Cannot resolve server address. Please check the server URL is correct.",
            { cause: error },
          );
        }
        // SSL/TLS errors
        else if (
          errMsg.includes("ssl") ||
          errMsg.includes("tls") ||
          errMsg.includes("certificate") ||
          errMsg.includes("cert")
        ) {
          this.setAuthStatus("unauthenticated", null);
          throw new Error(
            "SSL/TLS certificate error. Server may have an invalid or self-signed certificate.",
            {
              cause: error,
            },
          );
        }
        // 404 - endpoint not found
        else if (errMsg.includes("404") || errMsg.includes("not found")) {
          this.setAuthStatus("unauthenticated", null);
          throw new Error(
            "Login endpoint not found. Please ensure you are connecting to a valid Stirling PDF server.",
            {
              cause: error,
            },
          );
        }
        // 403 - security disabled
        else if (errMsg.includes("403") || errMsg.includes("forbidden")) {

View on GitHub (pinned to 9ef20dcab8)

Solutions

1. Install a trusted certificate on the server (Let's Encrypt or a CA the desktop trusts).
2. 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).
3. Verify the cert hostname matches the server URL host (no IP-vs-cert-mismatch).
4. Renew the cert if it has expired.

Example fix

// before: self-signed cert rejected by desktop trust store
//   https://stirling.local  -> SSL/TLS certificate error
// after: install the server's root CA on the desktop, then
await authService.login('https://stirling.local', user, pass);

// require https for production servers and warn on suspicious certs up front
const u = new URL(serverUrl);
if (u.protocol !== 'https:') { warn('This server uses HTTP — credentials will be sent unencrypted.'); }

function isTlsError(e: unknown): e is Error {
  return e instanceof Error && /SSL\/TLS certificate error/.test(e.message);
}

try { await authService.login(serverUrl, user, pass); }
catch (e) {
  if (isTlsError(e)) { show('The server certificate is untrusted. Install its root CA or use a trusted cert.'); return; }
  throw e;
}

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• Sign up failed
• Cannot connect to server. Please check the server URL and en
• Login request timed out. Please check your network connectio
• Cannot resolve server address. Please check the server URL i
• Download failed (${response.status})

AI-assisted analysis of Stirling-Tools/Stirling-PDF@9ef20dcab8 (2026-08-13). Data as JSON: /api/errors/fafa05bacd6d57d8. Report an issue: GitHub.