Stirling-Tools/Stirling-PDF · error · Error

Cannot resolve server address. Please check the server URL i

Error message

Cannot resolve server address. Please check the server URL is correct.

What it means

Thrown when the login error message contains 'getaddrinfo', 'dns', 'not found', or 'enotfound'. DNS resolution for the server hostname failed — the name does not resolve to an address. Original error preserved as cause; auth resets to unauthenticated.

Source

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

        // 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 (
          errMsg.includes("getaddrinfo") ||
          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,
            },
          );

View on GitHub (pinned to 9ef20dcab8)

Solutions

Double-check the hostname spelling in the server URL.
Ensure the desktop is on the network where the hostname resolves (VPN connected for corporate hosts).
Try resolving the host (nslookup/dig) from the desktop; if it fails, fix DNS or use an IP address.
For LAN hosts, confirm mDNS / local DNS is publishing the name.

Example fix

// before: user enters internal-only name from outside the LAN
//   http://stirling.internal:8080
// after: preflight DNS check with a helpful hint
const resolved = await canResolve(new URL(serverUrl).hostname);
if (!resolved) { hint('That hostname does not resolve from here — check it or connect to the LAN/VPN.'); return; }
await authService.login(serverUrl, user, pass);

Defensive patterns

Strategy: validation

Validate before calling

// preflight hostname resolution hint
async function canResolve(host: string): Promise<boolean> {
  try { await fetch(`https://${host}/api/v1/info`, { method: 'HEAD', signal: AbortSignal.timeout(3000) }); return true; }
  catch (e) { return !/ENOTFOUND|getaddrinfo|dns/i.test(String(e)); }
}

Type guard

function isDnsFailure(e: unknown): e is Error {
  return e instanceof Error && /Cannot resolve server address/.test(e.message);
}

Try / catch

try { await authService.login(serverUrl, user, pass); }
catch (e) {
  if (isDnsFailure(e)) { show('That hostname does not resolve — check it or connect to the LAN/VPN.'); return; }
  throw e;
}

Prevention

Normalize/validate the server URL (new URL()) before login.
For corporate hosts, remind users to connect to VPN first.
Suggest the IP address as a fallback when DNS is unavailable.

When it happens

Trigger: The server URL host cannot be resolved: a typo in the hostname, an internal-only DNS name used from outside the VPN, a split-horizon DNS mismatch, or the resolver being unreachable.

Common situations: User typed the server's internal Docker hostname instead of the host machine's address; private hostname only resolvable on the corporate LAN but the desktop is remote; custom DNS server misconfigured or down.

Related errors

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