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 guard as the create-workspace path, but for connecting a remote workspace: WelcomeRoute must first fetch the workspace list from the local OpenWork server, and if that fetch fails (list = null) the flow aborts with this message. The local server acts as the broker for remote workspace connections, so it must be reachable even though the workspace itself is remote.

Source

Thrown at apps/app/src/react-app/shell/welcome-route.tsx:309

        if (isDesktopRuntime()) {
          list = await workspaceCreateRemote(payload);
        } else {
          try {
            const { normalizedBaseUrl, resolvedToken, resolvedHostToken } =
              await resolveOpenworkConnection();
            if (normalizedBaseUrl && (resolvedToken || resolvedHostToken)) {
              list = await createOpenworkServerClient({
                baseUrl: normalizedBaseUrl,
                token: resolvedToken || undefined,
                hostToken: resolvedHostToken || undefined,
              }).createRemoteWorkspace(payload);
            }
          } catch {
            list = 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);
          writeActiveWorkspaceId(createdId);
        }
        markOnboardingComplete();
        dispatch({ type: "close" });
        navigate(createdId ? workspaceSessionRoute(createdId) : "/session", { replace: true });
        return true;
      } catch (error) {
        dispatch({
          type: "remote:error",
          error: error instanceof Error ? error.message : "Connection failed.",

View on GitHub (pinned to 2b7df46e8a)

Solutions

Start/reconnect the local OpenWork server and retry the remote connect
Verify the server URL and that /workspaces responds (curl the endpoint)
Re-authenticate if the token is stale
Retry after a transient network failure

Example fix

// before
const list = await getWorkspaceList(token);
connectRemote(list.workspaces);
// after
const list = await getWorkspaceList(token).catch(() => null);
if (!list) throw new Error("OpenWork server is unavailable. Start or reconnect the server before connecting a remote workspace.");

Defensive patterns

Strategy: validation

Validate before calling

const list = await fetch(`${serverUrl}/workspaces`, { headers: { Authorization: `Bearer ${token}` } }).then(r => r.ok ? r.json() : null).catch(() => null);
if (!list?.workspaces) throw new Error("Connect the OpenWork server before connecting a remote workspace");

Type guard

function hasWorkspaceList(v) {
  return v !== null && typeof v === "object" && Array.isArray(v.workspaces);
}

Prevention

Gate remote-connect UI on a live server health check
Retry the list fetch once with short backoff before surfacing the error
Keep the session token fresh; re-auth on 401
Log the underlying fetch failure that nulls the list to speed diagnosis

When it happens

Trigger: Clicked 'connect remote workspace' while the workspace-list request to the local server threw or returned nothing, hitting the `if (!list)` guard at welcome-route.tsx:309.

Common situations: Server not running or just disconnected; network flake during onboarding; session token invalid so the list call errors; user trying to connect a remote workspace before completing local server setup.

Related errors

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