hcengineering/platform · error · PlatformError

WorkspaceNotFound

WorkspaceNotFound

Error message

WorkspaceNotFound

What it means

WorkspaceNotFound is thrown by updateWorkspaceInfo when no workspace exists in the account database with the given workspaceUuid. After validating auth and parameters, the service checks db.workspace.exists({ uuid }) and aborts with this status (including the requested workspaceUuid in the error data). The workspace was deleted, never created, or the UUID is wrong/foreign to this deployment.

Source

Thrown at server/account/src/serviceOperations.ts:327

    message?: string
  }
): Promise<void> {
  const { workspaceUuid, event, version, message } = params

  const { extra } = decodeTokenVerbose(ctx, token)
  if (!['workspace', 'tool'].includes(extra?.service)) {
    throw new PlatformError(new Status(Severity.ERROR, platform.status.Forbidden, {}))
  }

  if (workspaceUuid == null || workspaceUuid === '' || event == null) {
    throw new PlatformError(new Status(Severity.ERROR, platform.status.BadRequest, {}))
  }

  let progress = params.progress

  const wsExists = await db.workspace.exists({ uuid: workspaceUuid })
  if (!wsExists) {
    throw new PlatformError(new Status(Severity.ERROR, platform.status.WorkspaceNotFound, { workspaceUuid }))
  }
  progress = Math.round(progress)

  const ts = Date.now()
  const update: Partial<WorkspaceStatus> = {}
  const wsUpdate: Partial<Workspace> = {}
  const query: Query<WorkspaceStatus> = { workspaceUuid }

  // Only read status for certain events because it is not needed for others
  // and it interferes with status updates when concurrency is high
  let wsStatus: WorkspaceStatus | null = null
  if (['create-started', 'upgrade-started', 'migrate-clean-done'].includes(event)) {
    wsStatus = await db.workspaceStatus.findOne({ workspaceUuid })
  }
  switch (event) {
    case 'create-started':
      update.mode = 'creating'
      if (wsStatus != null && wsStatus.mode !== 'creating') {

View on GitHub (pinned to 63e28dc964)

Solutions

1. Verify the workspaceUuid exists (query db.workspace or a get-workspace API) before sending updates, and skip/ignore updates for missing workspaces.
2. Check you are calling the correct deployment/database where the workspace was created.
3. Refresh the workspace ID from the create-workspace response instead of reusing cached values.
4. Treat this status as terminal in the worker: stop the update loop for that workspace rather than retrying.

Example fix

// before
await accountClient.updateWorkspaceInfo(ctx, token, { workspaceUuid, event })

// after
try {
  await accountClient.updateWorkspaceInfo(ctx, token, { workspaceUuid, event })
} catch (err) {
  if (err instanceof PlatformError && err.status.code === platform.status.WorkspaceNotFound) {
    return // workspace gone; drop the update instead of failing
  }
  throw err
}

// Check the workspace exists before sending updates
const exists = await db.workspace.exists({ uuid: workspaceUuid })
if (!exists) {
  log.warn('Skipping update; workspace no longer exists', { workspaceUuid })
  return
}

function isWorkspaceNotFoundError(err: unknown): err is PlatformError<WorkspaceNotFound> {
  return err instanceof PlatformError && err.status.code === platform.status.WorkspaceNotFound
}

try {
  await updateWorkspaceInfo(ctx, token, { workspaceUuid, event })
} catch (err) {
  if (isWorkspaceNotFoundError(err)) {
    log.warn('Workspace disappeared; dropping update', { workspaceUuid })
    return
  }
  throw err
}

When it happens

Trigger: Calling updateWorkspaceInfo with a workspaceUuid that has no matching workspace row: workspace already deleted, UUID typo'd or from another environment/region, workspace creation rolled back, or stale ID cached by the caller after deletion.

Common situations: A tool service continues posting progress events for a workspace removed concurrently by a user; dev/staging UUIDs used against a prod account DB; tests reusing hard-coded workspace UUIDs; migrations or region failover leaving the account DB without the workspace record.

Related errors

• platform.status.WorkspaceNotFound
• account.status.WorkspaceNotFound
• account.status.WorkspaceNotFound
• WorkspaceNotFound
• Invalid workspace: '${user.workspace}'

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