Stirling-Tools/Stirling-PDF · error · Error

Cannot connect to server. Please check the server URL and en

Error message

Cannot connect to server. Please check the server URL and ensure the server is running.

What it means

Thrown when the login error message contains 'connection refused' or 'econnrefused'. The TCP connection to the server was actively refused — the host was reachable but nothing is listening on the configured port. Original error preserved as cause; auth resets to unauthenticated.

Source

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

          errMsg.includes("401") ||
          errMsg.includes("unauthorized") ||
          errMsg.includes("invalid credentials")
        ) {
          this.setAuthStatus("unauthenticated", null);
          throw new Error(
            "Invalid username or password. Please check your credentials and try again.",
            {
              cause: error,
            },
          );
        }
        // Server not found or unreachable
        else if (
          errMsg.includes("connection refused") ||
          errMsg.includes("econnrefused")
        ) {
          this.setAuthStatus("unauthenticated", null);
          throw new Error(
            "Cannot connect to server. Please check the server URL and ensure the server is running.",
            {
              cause: error,
            },
          );
        }
        // Timeout
        else if (errMsg.includes("timeout") || errMsg.includes("timed out")) {
          this.setAuthStatus("unauthenticated", null);
          throw new Error(
            "Login request timed out. Please check your network connection and try again.",
            {
              cause: error,
            },
          );
        }
        // DNS failure
        else if (

View on GitHub (pinned to 9ef20dcab8)

Solutions

1. Verify the Stirling PDF server process/container is running and healthy.
2. Confirm the port in the server URL matches the published/host port (docker -p hostPort:8080), not the internal 8080.
3. Check the URL scheme: use https:// only if the listener serves TLS.
4. Ensure no firewall/security group is dropping the port between the desktop and the server.

Example fix

// before: user types http://srv:8080 but container publishes 9090
// after: validate reachability before login and hint the real port
const ok = await probeTcp(serverHost, serverPort);
if (!ok) { hint('Nothing is listening — is the server running and is the port correct?'); return; }
await authService.login(serverUrl, user, pass);

// preflight TCP reachability check before login
async function isPortOpen(host: string, port: number, timeoutMs = 2000): Promise<boolean> {
  try { await fetch(`http://${host}:${port}/api/v1/info`, { method: 'HEAD', signal: AbortSignal.timeout(timeoutMs) }); return true; }
  catch { return false; }
}

function isConnectionRefused(e: unknown): e is Error {
  return e instanceof Error && /Cannot connect to server/.test(e.message);
}

try { await authService.login(serverUrl, user, pass); }
catch (e) {
  if (isConnectionRefused(e)) { show('Nothing is listening on that server/port — is it running?'); return; }
  throw e;
}

When it happens

Trigger: The configured server URL points at a host/port where no Stirling PDF process is listening; the backend crashed after startup; the user entered http://host:8080 but the server runs on 8080 only inside the container and is mapped to a different host port.

Common situations: Server container stopped; wrong port in the server URL (e.g. internal container port vs published host port); firewall/load-balancer rejecting the port; HTTPS URL pointed at an HTTP-only listener (or vice versa) producing a refuse.

Related errors

• Cannot resolve server address. Please check the server URL i
• Sign up failed
• Login request timed out. Please check your network connectio
• SSL/TLS certificate error. Server may have an invalid or sel
• Download failed (${response.status})

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