{"record":{"id":"459668bd7642a9c5","repo":"hcengineering/platform","slug":"connect-during-upgrade","errorCode":null,"errorMessage":"connect during upgrade","messagePattern":"connect during upgrade","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"foundations/server/packages/server/src/sessionManager.ts","lineNumber":671,"sourceCode":"      if (workspace.maintenance) {\n        ctx.warn('reconnect workspace in upgrade', {\n          account: token.account,\n          workspace: workspaceUuid,\n          wsUrl: workspaceInfo.url\n        })\n      } else {\n        ctx.warn('reconnect workspace in upgrade switch', {\n          email: token.account,\n          workspace: workspaceUuid,\n          wsUrl: workspaceInfo.url\n        })\n\n        // We need to wait in case previous upgrade connection is already closing.\n        await this.switchToUpgradeSession(token, ctx.parent ?? ctx, workspace, ws)\n      }\n    } else {\n      if (workspace.maintenance || this.maintenanceWorkspaces.has(workspace.wsId.uuid)) {\n        ctx.warn('connect during upgrade', {\n          account: token.account,\n          workspace: workspace.wsId.url,\n          sessionUsers: Array.from(workspace.sessions.values()).map((it) => it.session.getUser()),\n          sessionData: Array.from(workspace.sessions.values()).map((it) => it.socket.data())\n        })\n\n        return { resp: { upgrade: true } }\n      }\n    }\n    return { workspace }\n  }\n\n  sysAccount = {\n    account: systemAccountUuid,\n    name: 'System',\n    workspaces: {},\n    socialIds: []\n  }","sourceCodeStart":653,"sourceCodeEnd":689,"githubUrl":"https://github.com/hcengineering/platform/blob/63e28dc96483967b2fc21c881b3f1023c1de7718/foundations/server/packages/server/src/sessionManager.ts#L653-L689","documentation":"Warning logged by getWorkspace when a NORMAL (non-upgrade) client tries to connect while the workspace is in maintenance mode (workspace.maintenance or listed in maintenanceWorkspaces), i.e., during an upgrade. The server rejects the connection by returning { resp: { upgrade: true } } so the client shows an 'upgrading' state and retries later instead of joining a workspace being migrated.","triggerScenarios":"getWorkspace with token.extra?.model !== 'upgrade' and (workspace.maintenance === true OR this.maintenanceWorkspaces.has(workspace.wsId.uuid)). The log captures the account plus all current session users and socket data for debugging the upgrade state.","commonSituations":"Users reconnecting (browser refresh, network blip) while a model upgrade is in progress; scheduled upgrades running during business hours; a workspace stuck in maintenance after a failed upgrade so all user connections bounce.","solutions":["Wait for the upgrade to complete — the client should honor the { upgrade: true } response and re-attempt connection afterwards.","If the workspace is stuck in maintenance, complete or restart the upgrade, or call forceClose(wsId) to clear maintenanceWorkspaces/maintenance and rebuild the workspace.","Schedule upgrades in maintenance windows and add client UX that surfaces the 'upgrading' state to reduce reconnect storms.","Check upgrade progress reporting (workspaceInfo.progress) so clients can show status instead of retrying aggressively."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"const info = await workspaceService.getWorkspaceInfo(wsUuid)\nif (info?.mode === 'upgrading') {\n  scheduleReconnectWithBackoff(wsUuid)\n  return\n}","typeGuard":"function isWorkspaceAvailable(ws: Workspace | undefined, maintenanceWorkspaces: Set<WorkspaceUuid>): boolean {\n  return ws !== undefined && !ws.maintenance && !maintenanceWorkspaces.has(ws.wsId.uuid)\n}","tryCatchPattern":"const { workspace, resp } = await sessionManager.getWorkspace(ctx, wsUuid, info, token, socket)\nif (!workspace && resp?.upgrade) {\n  showUpgradingUI()\n  await reconnectAfterUpgrade(wsUuid) // retry with exponential backoff\n}","preventionTips":["Schedule upgrades in maintenance windows and notify users in advance.","Implement client-side exponential backoff for reconnects during upgrade to avoid hammering the server.","Surface the 'upgrading' state in client UX instead of silent retries.","Alert when a workspace stays in maintenance beyond the expected upgrade duration."],"tags":["upgrade","maintenance-mode","connectivity","workspace"],"backgroundTag":"workspace-in-maintenance","analyzedSha":"63e28dc96483967b2fc21c881b3f1023c1de7718","analyzedAt":"2026-08-29T15:21:27.377Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}