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 creating a workspace.

What it means

WelcomeRoute's workspace-creation flow tries to load the workspace list from the local OpenWork server; if the request throws or returns null, it raises this error instead of silently creating a workspace. The server's /workspaces endpoint is a hard prerequisite for creating a workspace, so its absence aborts onboarding. This converts a network/transport failure into an actionable user-facing message telling them to start or reconnect the server.

Source

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

          if (normalizedBaseUrl && (resolvedToken || resolvedHostToken)) {
            const openworkClient = createOpenworkServerClient({
              baseUrl: normalizedBaseUrl,
              token: resolvedToken || undefined,
              hostToken: resolvedHostToken || undefined,
            });
            list = await openworkClient.createLocalWorkspace({
              folderPath: folder,
              name: workspaceName,
              preset: "starter",
            });
            sessionBaseUrl = normalizedBaseUrl;
            sessionToken = resolvedToken;
          }
        } catch {
          list = null;
        }
        if (!list) {
          throw new Error("OpenWork server is unavailable. Start or reconnect the server before creating a workspace.");
        }
        const createdId =
          resolveWorkspaceListSelectedId(list) ||
          list.workspaces[list.workspaces.length - 1]?.id ||
          "";
        let targetWorkspaceId = createdId;
        let targetWorkspace = list.workspaces.find((workspace: WorkspaceInfo) => workspace.id === createdId) ?? null;
        let targetSessionId: string | null = null;
        if (createdId) {
          await workspaceSetSelected(createdId).catch(() => undefined);
          await workspaceSetRuntimeActive(createdId).catch(() => undefined);
          writeActiveWorkspaceId(createdId);
        }
        if (targetWorkspace) {
          await ensureDesktopLocalOpenworkConnection({
            route: "session",
            workspace: targetWorkspace,
            allWorkspaces: list.workspaces,

View on GitHub (pinned to 2b7df46e8a)

Solutions

Start or reconnect the OpenWork server, then retry workspace creation
Check the server process/port health and restart the desktop app if it died
Re-authenticate (session token) if the list request fails due to auth
Inspect logs for the underlying fetch failure that set list to null

Example fix

// before: user clicks create with server down -> unhelpful hang or raw fetch error
const list = await fetchWorkspaceList();
// after: guard before calling create
const list = await fetchWorkspaceList().catch(() => null);
if (!list) throw new Error("OpenWork server is unavailable. Start or reconnect the server before creating a workspace.");

Defensive patterns

Strategy: try-catch

Validate before calling

// Check server reachability before creating a workspace
const res = await fetch(`${serverUrl}/workspaces`, { headers: { Authorization: `Bearer ${token}` } }).catch(() => null);
if (!res?.ok) throw new Error("Start the OpenWork server before creating a workspace");

Try / catch

try {
  await createWorkspace();
} catch (err) {
  if (err.message.includes("server is unavailable")) {
    await reconnectServer(); // then retry once
    await createWorkspace();
  } else throw err;
}

Prevention

Ping /workspaces (or a health endpoint) before any workspace mutation
Show server connection state in the UI and disable create actions while disconnected
Re-validate the session token on app start
Auto-reconnect the server with backoff on app launch

When it happens

Trigger: Clicked 'create workspace' in the welcome/onboarding route while the local openwork-server is not running, has exited, or the authenticated request to fetch the workspace list fails (list resolves to null in the try/catch before line 205).

Common situations: Fresh install where the server was never started; server process crashed or was killed; dev running only the renderer without the server; stale auth/session token making the list call fail.

Related errors

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