{"record":{"id":"5125aa00a9bfae0e","repo":"different-ai/openwork","slug":"openwork-server-is-unavailable-start-or-reconnect-5125aa","errorCode":null,"errorMessage":"OpenWork server is unavailable. Start or reconnect the server before creating a workspace.","messagePattern":"OpenWork server is unavailable\\. Start or reconnect the server before creating a workspace\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"apps/app/src/react-app/shell/welcome-route.tsx","lineNumber":205,"sourceCode":"          if (normalizedBaseUrl && (resolvedToken || resolvedHostToken)) {\n            const openworkClient = createOpenworkServerClient({\n              baseUrl: normalizedBaseUrl,\n              token: resolvedToken || undefined,\n              hostToken: resolvedHostToken || undefined,\n            });\n            list = await openworkClient.createLocalWorkspace({\n              folderPath: folder,\n              name: workspaceName,\n              preset: \"starter\",\n            });\n            sessionBaseUrl = normalizedBaseUrl;\n            sessionToken = resolvedToken;\n          }\n        } catch {\n          list = null;\n        }\n        if (!list) {\n          throw new Error(\"OpenWork server is unavailable. Start or reconnect the server before creating a workspace.\");\n        }\n        const createdId =\n          resolveWorkspaceListSelectedId(list) ||\n          list.workspaces[list.workspaces.length - 1]?.id ||\n          \"\";\n        let targetWorkspaceId = createdId;\n        let targetWorkspace = list.workspaces.find((workspace: WorkspaceInfo) => workspace.id === createdId) ?? null;\n        let targetSessionId: string | null = null;\n        if (createdId) {\n          await workspaceSetSelected(createdId).catch(() => undefined);\n          await workspaceSetRuntimeActive(createdId).catch(() => undefined);\n          writeActiveWorkspaceId(createdId);\n        }\n        if (targetWorkspace) {\n          await ensureDesktopLocalOpenworkConnection({\n            route: \"session\",\n            workspace: targetWorkspace,\n            allWorkspaces: list.workspaces,","sourceCodeStart":187,"sourceCodeEnd":223,"githubUrl":"https://github.com/different-ai/openwork/blob/2b7df46e8ae1517d64c896c7793d2d52ec845669/apps/app/src/react-app/shell/welcome-route.tsx#L187-L223","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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"],"exampleFix":"// before: user clicks create with server down -> unhelpful hang or raw fetch error\nconst list = await fetchWorkspaceList();\n// after: guard before calling create\nconst list = await fetchWorkspaceList().catch(() => null);\nif (!list) throw new Error(\"OpenWork server is unavailable. Start or reconnect the server before creating a workspace.\");","handlingStrategy":"try-catch","validationCode":"// Check server reachability before creating a workspace\nconst res = await fetch(`${serverUrl}/workspaces`, { headers: { Authorization: `Bearer ${token}` } }).catch(() => null);\nif (!res?.ok) throw new Error(\"Start the OpenWork server before creating a workspace\");","typeGuard":null,"tryCatchPattern":"try {\n  await createWorkspace();\n} catch (err) {\n  if (err.message.includes(\"server is unavailable\")) {\n    await reconnectServer(); // then retry once\n    await createWorkspace();\n  } else throw err;\n}","preventionTips":["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"],"tags":["server-unavailable","onboarding","network"],"backgroundTag":"server-unavailable","analyzedSha":"2b7df46e8ae1517d64c896c7793d2d52ec845669","analyzedAt":"2026-09-01T07:59:23.713Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}