hcengineering/platform · warning

connect during upgrade

Error message

connect during upgrade

What it means

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.

Source

Thrown at foundations/server/packages/server/src/sessionManager.ts:671

      if (workspace.maintenance) {
        ctx.warn('reconnect workspace in upgrade', {
          account: token.account,
          workspace: workspaceUuid,
          wsUrl: workspaceInfo.url
        })
      } else {
        ctx.warn('reconnect workspace in upgrade switch', {
          email: token.account,
          workspace: workspaceUuid,
          wsUrl: workspaceInfo.url
        })

        // We need to wait in case previous upgrade connection is already closing.
        await this.switchToUpgradeSession(token, ctx.parent ?? ctx, workspace, ws)
      }
    } else {
      if (workspace.maintenance || this.maintenanceWorkspaces.has(workspace.wsId.uuid)) {
        ctx.warn('connect during upgrade', {
          account: token.account,
          workspace: workspace.wsId.url,
          sessionUsers: Array.from(workspace.sessions.values()).map((it) => it.session.getUser()),
          sessionData: Array.from(workspace.sessions.values()).map((it) => it.socket.data())
        })

        return { resp: { upgrade: true } }
      }
    }
    return { workspace }
  }

  sysAccount = {
    account: systemAccountUuid,
    name: 'System',
    workspaces: {},
    socialIds: []
  }

View on GitHub (pinned to 63e28dc964)

Solutions

  1. Wait for the upgrade to complete — the client should honor the { upgrade: true } response and re-attempt connection afterwards.
  2. If the workspace is stuck in maintenance, complete or restart the upgrade, or call forceClose(wsId) to clear maintenanceWorkspaces/maintenance and rebuild the workspace.
  3. Schedule upgrades in maintenance windows and add client UX that surfaces the 'upgrading' state to reduce reconnect storms.
  4. Check upgrade progress reporting (workspaceInfo.progress) so clients can show status instead of retrying aggressively.
Defensive patterns

Strategy: retry

Validate before calling

const info = await workspaceService.getWorkspaceInfo(wsUuid)
if (info?.mode === 'upgrading') {
  scheduleReconnectWithBackoff(wsUuid)
  return
}

Type guard

function isWorkspaceAvailable(ws: Workspace | undefined, maintenanceWorkspaces: Set<WorkspaceUuid>): boolean {
  return ws !== undefined && !ws.maintenance && !maintenanceWorkspaces.has(ws.wsId.uuid)
}

Try / catch

const { workspace, resp } = await sessionManager.getWorkspace(ctx, wsUuid, info, token, socket)
if (!workspace && resp?.upgrade) {
  showUpgradingUI()
  await reconnectAfterUpgrade(wsUuid) // retry with exponential backoff
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of hcengineering/platform@63e28dc964 (2026-08-29). Data as JSON: /api/errors/459668bd7642a9c5. Report an issue: GitHub.