{"record":{"id":"d5e72627f74581c5","repo":"different-ai/openwork","slug":"openwork-server-is-unavailable-start-or-reconnect","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/session-route.tsx","lineNumber":2742,"sourceCode":"    if (!folder) return;\n    const projectLabel = options?.projectLabel?.trim() ?? \"\";\n    setCreateWorkspaceBusy(true);\n    setCreateWorkspaceError(null);\n    try {\n      const workspaceName = folderNameFromPath(folder);\n      let list: WorkspaceList | null = null;\n      let createdOnServer = false;\n      if (client) {\n        list = await client\n          .createLocalWorkspace({ folderPath: folder, name: workspaceName, preset })\n          .then((serverList) => {\n            createdOnServer = true;\n            return serverList;\n          })\n          .catch(() => 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 = resolveWorkspaceListSelectedId(list) || list.workspaces[list.workspaces.length - 1]?.id || \"\";\n      let targetWorkspaceId = createdId;\n      let targetWorkspace = list.workspaces.find((workspace: WorkspaceInfo) => workspace.id === createdId) ?? null;\n      if (createdId) {\n        await workspaceSetSelected(createdId).catch(() => undefined);\n        await workspaceSetRuntimeActive(createdId).catch(() => undefined);\n      }\n      // First workspace on a fresh install: the OpenWork server was started\n      // engine-less (it only spawns OpenCode at boot when a workspace already\n      // exists), so sessions would hang forever. This boots the engine when\n      // it isn't running, same as the old /welcome flow did.\n      let sessionBaseUrl = baseUrl;\n      let sessionToken = token;\n      if (targetWorkspace && isDesktopRuntime()) {\n        await ensureDesktopLocalOpenworkConnection({\n          route: \"session\",\n          workspace: targetWorkspace,","sourceCodeStart":2724,"sourceCodeEnd":2760,"githubUrl":"https://github.com/different-ai/openwork/blob/2b7df46e8ae1517d64c896c7793d2d52ec845669/apps/app/src/react-app/shell/session-route.tsx#L2724-L2760","documentation":"SessionRoute's workspace-creation flow fetches the workspace list via the OpenWork server (or client.createWorkspace for web). When every attempt fails or returns null, the code intentionally raises this error instead of proceeding with an undefined workspace list, because a workspace cannot be created without a reachable server.","triggerScenarios":"Calling the 'create workspace' action while (a) running the web runtime and no `client` is configured, (b) the server request rejects (network down, server not started) and workspaceList() falls back to null via `.catch(() => null)`, or (c) the OpenWork server process has died so the list fetch resolves to null.","commonSituations":"Developer launches the web app without a running openwork-server; the local server crashed after sleep/restart; wrong server baseUrl in config; firewall or proxy blocking the server port.","solutions":["Start or reconnect the OpenWork server (desktop: restart it from the app; web: launch openwork-server locally) before retrying workspace creation.","Verify the server is reachable at its configured baseUrl/port and no firewall or proxy blocks it.","Check server logs for a crash and restart it; then retry the create-workspace action."],"exampleFix":"// before\nlist = await client.createWorkspace(payload).catch(() => null);\nif (!list) throw new Error(\"OpenWork server is unavailable...\");\n// after\nif (!isServerReachable(await healthCheck())) await reconnectServer();\nlist = await client.createWorkspace(payload).catch(() => null);","handlingStrategy":"try-catch","validationCode":"const reachable = await fetch(`${serverBaseUrl}/health`).then(r => r.ok).catch(() => false);\nif (!reachable) throw new Skip(\"server not running\");","typeGuard":"function hasServerClient(c: unknown): c is { createWorkspace: (p: unknown) => Promise<WorkspaceList> } {\n  return typeof c === \"object\" && c !== null && \"createWorkspace\" in c;\n}","tryCatchPattern":"try {\n  await createWorkspaceAction();\n} catch (e) {\n  if (e instanceof Error && e.message.includes(\"server is unavailable\")) {\n    await reconnectServer(); // then retry once\n  } else throw e;\n}","preventionTips":["Health-check the server before any workspace CRUD call.","Auto-reconnect the local server handle on app focus/wake.","Surface server status in the UI and disable create/connect actions while disconnected.","Retry transient fetch failures instead of resolving to null silently."],"tags":["network","server-unavailable","workspace-creation"],"backgroundTag":"server-unavailable","analyzedSha":"2b7df46e8ae1517d64c896c7793d2d52ec845669","analyzedAt":"2026-09-01T07:59:23.713Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}