different-ai/openwork · error · Error

OpenWork server is unavailable. Start or reconnect the serve

Error message

OpenWork server is unavailable. Start or reconnect the server before connecting a remote workspace.

What it means

Same family as the create-workspace guard: the 'connect remote workspace' path calls workspaceCreateRemote (desktop) or client.createRemoteWorkspace (web) and requires a non-null workspace list result. If both paths yield null, the server is effectively unreachable and the route throws instead of persisting a broken selection.

Source

Thrown at apps/app/src/react-app/shell/session-route.tsx:2915

    setCreateWorkspaceRemoteError(null);
    try {
      const remoteType: "openwork" = "openwork";
      const payload = {
        baseUrl: baseUrlValue,
        openworkHostUrl: baseUrlValue,
        openworkToken: input.openworkToken?.trim() || null,
        displayName: input.displayName?.trim() || null,
        directory: input.directory?.trim() || null,
        remoteType,
      };
      let list: WorkspaceList | null = null;
      if (isDesktopRuntime()) {
        list = await workspaceCreateRemote(payload);
      } else if (client) {
        list = await client.createRemoteWorkspace(payload).catch(() => null);
      }
      if (!list) {
        throw new Error("OpenWork server is unavailable. Start or reconnect the server before connecting a remote workspace.");
      }
      const createdId = resolveWorkspaceListSelectedId(list) || list.workspaces[list.workspaces.length - 1]?.id || "";
      if (createdId) {
        await workspaceSetSelected(createdId).catch(() => undefined);
        await workspaceSetRuntimeActive(createdId).catch(() => undefined);
      }
      setCreateWorkspaceOpen(false);
      // Mark onboarding complete so the /welcome redirect never fires again.
      local.setPrefs((prev) => ({ ...prev, hasCompletedOnboarding: true }));
      await refreshRouteState();
      return true;
    } catch (error) {
      setCreateWorkspaceRemoteError(error instanceof Error ? error.message : t("app.unknown_error"));
      return false;
    } finally {
      setCreateWorkspaceRemoteBusy(false);
    }
  }, [client, local, refreshRouteState]);

View on GitHub (pinned to 2b7df46e8a)

Solutions

Start or reconnect the OpenWork server, then retry connecting the remote workspace.
Confirm the server version implements createRemoteWorkspace; upgrade the server/client pair if mismatched.
Re-authenticate if the server token is stale (rejection may be auth-related surfaced as unavailability).

Example fix

// before
const list = await client.createRemoteWorkspace(payload).catch(() => null);
if (!list) throw new Error("OpenWork server is unavailable...");
// after
await ensureServerConnected();
const list = await client.createRemoteWorkspace(payload);

Defensive patterns

Strategy: retry

Validate before calling

if (!client || typeof client.createRemoteWorkspace !== "function") await ensureServerConnected();

Type guard

function canCreateRemote(c: unknown): c is { createRemoteWorkspace: (p: unknown) => Promise<WorkspaceList> } {
  return typeof c === "object" && c !== null && "createRemoteWorkspace" in c;
}

Try / catch

try {
  await connectRemoteWorkspace(payload);
} catch (e) {
  if (e instanceof Error && e.message.includes("server is unavailable")) {
    showServerReconnectPrompt();
  } else throw e;
}

Prevention

Verify server connectivity before offering remote-workspace connection.
Check server version implements createRemoteWorkspace.
Re-authenticate when token expiry is the root cause.
Do not swallow rejections with `.catch(() => null)` in app code — distinguish network vs API errors.

When it happens

Trigger: Invoking connect-remote-workspace when workspaceCreateRemote rejects on desktop, or client.createRemoteWorkspace rejects/is absent on web so `.catch(() => null)` returns null — i.e., the OpenWork server is down, misconfigured, or the client lacks the createRemoteWorkspace API.

Common situations: Adding a remote workspace URL while the local server is stopped; stale server token after re-auth; older server build that does not implement createRemoteWorkspace.

Related errors

AI-assisted analysis of different-ai/openwork@2b7df46e8a (2026-09-01). Data as JSON: /api/errors/02d67c6f5568adad. Report an issue: GitHub.