{"record":{"id":"a3927a1180ac83f0","repo":"Stirling-Tools/Stirling-PDF","slug":"cannot-connect-to-server-please-check-the-server","errorCode":null,"errorMessage":"Cannot connect to server. Please check the server URL and ensure the server is running.","messagePattern":"Cannot connect to server\\. Please check the server URL and ensure the server is running\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"frontend/editor/src/desktop/services/authService.ts","lineNumber":428,"sourceCode":"          errMsg.includes(\"401\") ||\n          errMsg.includes(\"unauthorized\") ||\n          errMsg.includes(\"invalid credentials\")\n        ) {\n          this.setAuthStatus(\"unauthenticated\", null);\n          throw new Error(\n            \"Invalid username or password. Please check your credentials and try again.\",\n            {\n              cause: error,\n            },\n          );\n        }\n        // Server not found or unreachable\n        else if (\n          errMsg.includes(\"connection refused\") ||\n          errMsg.includes(\"econnrefused\")\n        ) {\n          this.setAuthStatus(\"unauthenticated\", null);\n          throw new Error(\n            \"Cannot connect to server. Please check the server URL and ensure the server is running.\",\n            {\n              cause: error,\n            },\n          );\n        }\n        // Timeout\n        else if (errMsg.includes(\"timeout\") || errMsg.includes(\"timed out\")) {\n          this.setAuthStatus(\"unauthenticated\", null);\n          throw new Error(\n            \"Login request timed out. Please check your network connection and try again.\",\n            {\n              cause: error,\n            },\n          );\n        }\n        // DNS failure\n        else if (","sourceCodeStart":410,"sourceCodeEnd":446,"githubUrl":"https://github.com/Stirling-Tools/Stirling-PDF/blob/9ef20dcab80b85041912f045e17a6aea1d08f969/frontend/editor/src/desktop/services/authService.ts#L410-L446","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the Stirling PDF server process/container is running and healthy.","Confirm the port in the server URL matches the published/host port (docker -p hostPort:8080), not the internal 8080.","Check the URL scheme: use https:// only if the listener serves TLS.","Ensure no firewall/security group is dropping the port between the desktop and the server."],"exampleFix":"// before: user types http://srv:8080 but container publishes 9090\n// after: validate reachability before login and hint the real port\nconst ok = await probeTcp(serverHost, serverPort);\nif (!ok) { hint('Nothing is listening — is the server running and is the port correct?'); return; }\nawait authService.login(serverUrl, user, pass);","handlingStrategy":"validation","validationCode":"// preflight TCP reachability check before login\nasync function isPortOpen(host: string, port: number, timeoutMs = 2000): Promise<boolean> {\n  try { await fetch(`http://${host}:${port}/api/v1/info`, { method: 'HEAD', signal: AbortSignal.timeout(timeoutMs) }); return true; }\n  catch { return false; }\n}","typeGuard":"function isConnectionRefused(e: unknown): e is Error {\n  return e instanceof Error && /Cannot connect to server/.test(e.message);\n}","tryCatchPattern":"try { await authService.login(serverUrl, user, pass); }\ncatch (e) {\n  if (isConnectionRefused(e)) { show('Nothing is listening on that server/port — is it running?'); return; }\n  throw e;\n}","preventionTips":["Validate the server URL format and port before login.","Run a preflight reachability check on the server URL.","Distinguish host/port in the URL so users can correct just the port."],"tags":["network","connection-refused","server-config","desktop"],"backgroundTag":null,"analyzedSha":"9ef20dcab80b85041912f045e17a6aea1d08f969","analyzedAt":"2026-08-13T22:11:39.827Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}