Stirling-Tools/Stirling-PDF · error · Error

Unable to open system browser for SSO. Please check your sys

Error message

Unable to open system browser for SSO. Please check your system settings.

What it means

Thrown by loginWithSelfHostedOAuth when openInSystemBrowser(authUrl) resolves to false — the OS 'open URL' shell call declined/failed, so the SSO authorization page could never be shown to the user. The deep-link wait never starts because the browser step failed first.

Source

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

    const trimmedServer = serverUrl.replace(/\/+$/, "");
    const fullUrl = providerPath.startsWith("http")
      ? providerPath
      : `${trimmedServer}${providerPath.startsWith("/") ? providerPath : `/${providerPath}`}`;
    let authUrl = fullUrl;
    try {
      const parsed = new URL(fullUrl);
      parsed.searchParams.set("tauri", "1");
      parsed.searchParams.set("nonce", nonce);
      authUrl = parsed.toString();
    } catch {
      // ignore URL parsing failures
    }

    // Register deep-link listener before opening browser to avoid callback races on first launch.
    return this.waitForDeepLinkCompletion(trimmedServer, async () => {
      if (!(await this.openInSystemBrowser(authUrl))) {
        throw new Error(
          "Unable to open system browser for SSO. Please check your system settings.",
        );
      }
    });
  }

  /**
   * Wait for a deep-link event to complete self-hosted SSO after system browser OAuth
   */
  private async waitForDeepLinkCompletion(
    serverUrl: string,
    startFlow?: () => Promise<void>,
  ): Promise<UserInfo> {
    if (!isTauri()) {
      throw new Error(
        "Deep link authentication is only supported in Tauri desktop app.",
      );
    }

View on GitHub (pinned to 9ef20dcab8)

Solutions

1. Set a default web browser in the OS settings and retry.
2. Allow the desktop app to open external URLs (relax the OS/app-store policy that blocks it).
3. As a fallback, copy the authUrl to the clipboard and have the user paste it into a browser manually.
4. Verify the configured OAuth providerPath resolves to a full https:// URL before opening.

Example fix

// before: only throw on failure
if (!(await this.openInSystemBrowser(authUrl))) {
  throw new Error('Unable to open system browser for SSO…');
}

// after: fall back to clipboard copy + manual open
if (!(await this.openInSystemBrowser(authUrl))) {
  await writeText(authUrl);
  notify('Could not open the browser. We copied the sign-in link — paste it into your browser.');
}

// validate the OAuth URL is well-formed before opening
function isValidAuthUrl(u: string): boolean { try { const p = new URL(u); return p.protocol === 'http:' || p.protocol === 'https:'; } catch { return false; } }

function isBrowserOpenFailure(e: unknown): e is Error {
  return e instanceof Error && /Unable to open system browser/.test(e.message);
}

try { await authService.loginWithSelfHostedOAuth(providerPath, serverUrl); }
catch (e) {
  if (isBrowserOpenFailure(e)) { await writeText(authUrl); notify('We copied the sign-in link — open it in your browser.'); return; }
  throw e;
}

When it happens

Trigger: Tauri's shell.open (or the platform equivalent) returns false/throws: no default browser configured, the browser binary is missing or quarantined, an OS policy blocks opening external URLs, or the URL scheme is disallowed.

Common situations: Kiosk/locked-down machine with no default browser set; enterprise policy forbidding launching external apps; a browser binary that was uninstalled; sandboxed environment where shell.open is denied.

Related errors

• Failed to save authentication token
• No authentication token available
• Google Drive is not configured
• Could not get canvas context
• Database not initialized

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