{"record":{"id":"02d67c6f5568adad","repo":"different-ai/openwork","slug":"openwork-server-is-unavailable-start-or-reconnect-02d67c","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/session-route.tsx","lineNumber":2915,"sourceCode":"    setCreateWorkspaceRemoteError(null);\n    try {\n      const remoteType: \"openwork\" = \"openwork\";\n      const payload = {\n        baseUrl: baseUrlValue,\n        openworkHostUrl: baseUrlValue,\n        openworkToken: input.openworkToken?.trim() || null,\n        displayName: input.displayName?.trim() || null,\n        directory: input.directory?.trim() || null,\n        remoteType,\n      };\n      let list: WorkspaceList | null = null;\n      if (isDesktopRuntime()) {\n        list = await workspaceCreateRemote(payload);\n      } else if (client) {\n        list = await client.createRemoteWorkspace(payload).catch(() => null);\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 = resolveWorkspaceListSelectedId(list) || list.workspaces[list.workspaces.length - 1]?.id || \"\";\n      if (createdId) {\n        await workspaceSetSelected(createdId).catch(() => undefined);\n        await workspaceSetRuntimeActive(createdId).catch(() => undefined);\n      }\n      setCreateWorkspaceOpen(false);\n      // Mark onboarding complete so the /welcome redirect never fires again.\n      local.setPrefs((prev) => ({ ...prev, hasCompletedOnboarding: true }));\n      await refreshRouteState();\n      return true;\n    } catch (error) {\n      setCreateWorkspaceRemoteError(error instanceof Error ? error.message : t(\"app.unknown_error\"));\n      return false;\n    } finally {\n      setCreateWorkspaceRemoteBusy(false);\n    }\n  }, [client, local, refreshRouteState]);","sourceCodeStart":2897,"sourceCodeEnd":2933,"githubUrl":"https://github.com/different-ai/openwork/blob/2b7df46e8ae1517d64c896c7793d2d52ec845669/apps/app/src/react-app/shell/session-route.tsx#L2897-L2933","documentation":"Same family as the create-workspace guard: the 'connect remote workspace' path calls workspaceCreateRemote (desktop) or client.createRemoteWorkspace (web) and requires a non-null workspace list result. If both paths yield null, the server is effectively unreachable and the route throws instead of persisting a broken selection.","triggerScenarios":"Invoking connect-remote-workspace when workspaceCreateRemote rejects on desktop, or client.createRemoteWorkspace rejects/is absent on web so `.catch(() => null)` returns null — i.e., the OpenWork server is down, misconfigured, or the client lacks the createRemoteWorkspace API.","commonSituations":"Adding a remote workspace URL while the local server is stopped; stale server token after re-auth; older server build that does not implement createRemoteWorkspace.","solutions":["Start or reconnect the OpenWork server, then retry connecting the remote workspace.","Confirm the server version implements createRemoteWorkspace; upgrade the server/client pair if mismatched.","Re-authenticate if the server token is stale (rejection may be auth-related surfaced as unavailability)."],"exampleFix":"// before\nconst list = await client.createRemoteWorkspace(payload).catch(() => null);\nif (!list) throw new Error(\"OpenWork server is unavailable...\");\n// after\nawait ensureServerConnected();\nconst list = await client.createRemoteWorkspace(payload);","handlingStrategy":"retry","validationCode":"if (!client || typeof client.createRemoteWorkspace !== \"function\") await ensureServerConnected();","typeGuard":"function canCreateRemote(c: unknown): c is { createRemoteWorkspace: (p: unknown) => Promise<WorkspaceList> } {\n  return typeof c === \"object\" && c !== null && \"createRemoteWorkspace\" in c;\n}","tryCatchPattern":"try {\n  await connectRemoteWorkspace(payload);\n} catch (e) {\n  if (e instanceof Error && e.message.includes(\"server is unavailable\")) {\n    showServerReconnectPrompt();\n  } else throw e;\n}","preventionTips":["Verify server connectivity before offering remote-workspace connection.","Check server version implements createRemoteWorkspace.","Re-authenticate when token expiry is the root cause.","Do not swallow rejections with `.catch(() => null)` in app code — distinguish network vs API errors."],"tags":["network","server-unavailable","remote-workspace"],"backgroundTag":"server-unavailable","analyzedSha":"2b7df46e8ae1517d64c896c7793d2d52ec845669","analyzedAt":"2026-09-01T07:59:23.713Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}