Stirling-Tools/Stirling-PDF · warning · Error

This tool requires an account. Sign in to Stirling Cloud or…

Error message

This tool requires an account. Sign in to Stirling Cloud or connect to a self-hosted server to use it.

What it means

Thrown by operationRouter.getBaseUrl in local-only mode when the requested tool endpoint is not supported by the bundled local backend (endpointAvailabilityService.isEndpointSupportedLocally returns false). The app first dispatches an appConfig:navigate event to open connection settings, then throws this localized 'toolUnavailable' message telling the user they must sign in to use the tool.

Solutions

1. Sign in to Stirling Cloud or connect to a self-hosted server (the connection-settings panel was already opened for you) and retry the tool.
2. If self-hosting, ensure that server has the tool enabled and its dependencies installed.
3. For local use, install a backend build that includes the required capability.
4. Hide/disable tools the local backend cannot serve (consume endpointAvailabilityService in the UI).

Example fix

// before: tool button fires immediately
onClick={() => runTool(endpoint)}

// after: gate the button on local capability
const canRunLocal = mode !== 'local' || await endpointAvailabilityService.isEndpointSupportedLocally(name, backendUrl);
<button disabled={!canRunLocal} onClick={() => runTool(endpoint)} />

const mode = await connectionModeService.getCurrentMode();
const canRunLocal = mode !== 'local'
  || await endpointAvailabilityService.isEndpointSupportedLocally(endpointName, backendUrl);
if (!canRunLocal) { /* hide/disable the tool, prompt sign-in */ return; }

function isToolUnavailable(e: unknown): e is Error {
  return e instanceof Error && /requires an account/.test(e.message);
}

try { await runOperation(endpoint); }
catch (e) {
  if (isToolUnavailable(e)) { /* connection settings already opened; prompt sign-in */ return; }
  throw e;
}

When it happens

Trigger: User is in local-only mode (signed out / chose local) and triggers a tool the local backend cannot serve — e.g. a tool requiring a server-only feature, OCR model, or proprietary capability absent from the bundled backend.

Common situations: Local-only desktop user clicks a premium/server-only tool; the bundled backend lacks the endpoint or a heavy dependency (LibreOffice, OCR languages); the local backend is a stripped build.

Related errors

• Backend URL not available - backend may still be starting
• Backend did not become healthy after restart
• Cannot connect to server. Please check the server URL and…
• Cannot resolve server address. Please check the server URL…
• Connection mode is locked by provisioning

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

Appendix: source

Thrown at frontend/editor/src/desktop/services/operationRouter.ts:165

    // Local-only mode: route everything to local backend; open settings if tool unavailable
    if (mode === "local") {
      if (operation && this.isToolEndpoint(operation)) {
        const endpointName = this.extractEndpointName(operation);
        const backendUrl = tauriBackendService.getBackendUrl();
        if (backendUrl) {
          const supportedLocally =
            await endpointAvailabilityService.isEndpointSupportedLocally(
              endpointName,
              backendUrl,
            );
          if (!supportedLocally) {
            // Open the connection settings so the user can sign in
            window.dispatchEvent(
              new CustomEvent("appConfig:navigate", {
                detail: { key: "connectionMode" },
              }),
            );
            throw new Error(
              i18n.t(
                "localMode.toolUnavailable",
                "This tool requires an account. Sign in to Stirling Cloud or connect to a self-hosted server to use it.",
              ),
            );
          }
        }
      }
      const backendUrl = tauriBackendService.getBackendUrl();
      if (!backendUrl) {
        throw new Error(
          "Backend URL not available - backend may still be starting",
        );
      }
      return backendUrl.replace(/\/$/, "");
    }

    // Always route team endpoints to SaaS backend (existing logic)

View on GitHub (pinned to 9ef20dcab8)