{"record":{"id":"54f443721471b360","repo":"different-ai/openwork","slug":"openwork-server-is-unavailable-start-or-reconnect-54f443","errorCode":null,"errorMessage":"OpenWork server is unavailable. Start or reconnect the server before connecting a remote workspace.","messagePattern":"OpenWork server is unavailable\\. Start or reconnect the server before connecting a remote workspace\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"apps/app/src/react-app/shell/welcome-route.tsx","lineNumber":309,"sourceCode":"        if (isDesktopRuntime()) {\n          list = await workspaceCreateRemote(payload);\n        } else {\n          try {\n            const { normalizedBaseUrl, resolvedToken, resolvedHostToken } =\n              await resolveOpenworkConnection();\n            if (normalizedBaseUrl && (resolvedToken || resolvedHostToken)) {\n              list = await createOpenworkServerClient({\n                baseUrl: normalizedBaseUrl,\n                token: resolvedToken || undefined,\n                hostToken: resolvedHostToken || undefined,\n              }).createRemoteWorkspace(payload);\n            }\n          } catch {\n            list = null;\n          }\n        }\n        if (!list) {\n          throw new Error(\"OpenWork server is unavailable. Start or reconnect the server before connecting a remote workspace.\");\n        }\n        const createdId =\n          resolveWorkspaceListSelectedId(list) ||\n          list.workspaces[list.workspaces.length - 1]?.id ||\n          \"\";\n        if (createdId) {\n          await workspaceSetSelected(createdId).catch(() => undefined);\n          await workspaceSetRuntimeActive(createdId).catch(() => undefined);\n          writeActiveWorkspaceId(createdId);\n        }\n        markOnboardingComplete();\n        dispatch({ type: \"close\" });\n        navigate(createdId ? workspaceSessionRoute(createdId) : \"/session\", { replace: true });\n        return true;\n      } catch (error) {\n        dispatch({\n          type: \"remote:error\",\n          error: error instanceof Error ? error.message : \"Connection failed.\",","sourceCodeStart":291,"sourceCodeEnd":327,"githubUrl":"https://github.com/different-ai/openwork/blob/2b7df46e8ae1517d64c896c7793d2d52ec845669/apps/app/src/react-app/shell/welcome-route.tsx#L291-L327","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nconst list = await getWorkspaceList(token);\nconnectRemote(list.workspaces);\n// after\nconst list = await getWorkspaceList(token).catch(() => null);\nif (!list) throw new Error(\"OpenWork server is unavailable. Start or reconnect the server before connecting a remote workspace.\");","handlingStrategy":"validation","validationCode":"const list = await fetch(`${serverUrl}/workspaces`, { headers: { Authorization: `Bearer ${token}` } }).then(r => r.ok ? r.json() : null).catch(() => null);\nif (!list?.workspaces) throw new Error(\"Connect the OpenWork server before connecting a remote workspace\");","typeGuard":"function hasWorkspaceList(v) {\n  return v !== null && typeof v === \"object\" && Array.isArray(v.workspaces);\n}","tryCatchPattern":null,"preventionTips":["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"],"tags":["server-unavailable","remote-workspace","network"],"backgroundTag":"server-unavailable","analyzedSha":"2b7df46e8ae1517d64c896c7793d2d52ec845669","analyzedAt":"2026-09-01T07:59:23.713Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}