hcengineering/platform · warning

Model version mismatch

Error message

Model version mismatch

What it means

Warning emitted by TSessionManager.getWorkspace when a client's token asks to connect to a workspace whose data model version differs from the server's running modelVersion, and the connection is neither an 'upgrade' model connection nor a 'backup' mode connection. The server refuses the connection and responds with { upgrade: true } so the client reconnects and runs the model upgrade flow first.

Source

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

    if (isWorkspaceCreating(workspaceInfo.mode)) {
      // No access to workspace for token.
      return { resp: { error: new Error(`Workspace during creation phase...${workspaceUuid}`) } }
    }

    const wsVersion: Data<Version> = {
      major: workspaceInfo.version.versionMajor,
      minor: workspaceInfo.version.versionMinor,
      patch: workspaceInfo.version.versionPatch
    }

    if (
      this.modelVersion !== '' &&
      this.modelVersion !== versionToString(wsVersion) &&
      token.extra?.model !== 'upgrade' &&
      token.extra?.mode !== 'backup'
    ) {
      ctx.warn('Model version mismatch', {
        source: token.extra?.service ?? 'user',
        version: this.modelVersion,
        workspaceVersion: versionToString(wsVersion),
        workspace: workspaceUuid
      })
      // Version mismatch, return upgrading.
      return {
        resp: { upgrade: true, progress: workspaceInfo.mode === 'upgrading' ? (workspaceInfo.progress ?? 0) : 0 }
      }
    }

    let workspace = this.workspaces.get(workspaceUuid)
    if (workspace?.closing !== undefined) {
      await workspace?.closing
    }

    workspace = this.workspaces.get(workspaceUuid)

View on GitHub (pinned to 63e28dc964)

Solutions

1. Let the client follow the 'upgrade' response: reconnect with token.extra.model='upgrade' so switchToUpgradeSession / the upgrade pipeline migrates the workspace model.
2. Verify the workspace's registered version in the workspace service matches the server's modelVersion; trigger an upgrade job for lagging workspaces.
3. If this is an intentional backup/restore operation, ensure the token carries extra.mode='backup' so the mismatch check is skipped.
4. Check that workspaceInfo.version returned by the workspace service is not stale (clear workspaceInfoCache or force a refresh).

const wsInfo = await workspaceService.getWorkspaceInfo(wsUuid)
const wsVersion = `${wsInfo.version.versionMajor}.${wsInfo.version.versionMinor}.${wsInfo.version.versionPatch}`
if (wsVersion !== serverModelVersion && token.extra?.model !== 'upgrade') {
  await triggerWorkspaceUpgrade(wsUuid)
}

function canConnect(modelVersion: string, wsVersion: string, token: Token): boolean {
  return modelVersion === '' || modelVersion === wsVersion || token.extra?.model === 'upgrade' || token.extra?.mode === 'backup'
}

const { resp, workspace } = await sessionManager.getWorkspace(ctx, wsUuid, info, token, socket)
if (resp?.upgrade) {
  await reconnectWithUpgradeToken(wsUuid) // retry with token.extra.model = 'upgrade'
}

When it happens

Trigger: getWorkspace is called and: this.modelVersion !== '' AND this.modelVersion !== versionToString(wsVersion) (computed from workspaceInfo.version.versionMajor/Minor/Patch) AND token.extra?.model !== 'upgrade' AND token.extra?.mode !== 'backup'. The workspaceInfo comes from the workspace service; the mismatch means the workspace DB has not been migrated to the server's version yet.

Common situations: Server deployed with a new model version while the workspace still points at the old version; client tools bypassing the upgrade endpoint and connecting with a normal user token mid-rollout; stale workspaceInfo cache after a failed upgrade; backup-mode exclusions not applied because token.extra.mode is unset.

Related errors

• reconnect workspace in upgrade
• reconnect workspace in upgrade switch
• connect during upgrade
• No versions found for the specified version range.
• Unable to resolve version ${version} of package ${name}: ${e

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