hcengineering/platform · error

workspaceUuid is required

Error message

workspaceUuid is required

What it means

WorkspaceStatusMongoDbCollection.insertOne stores status data embedded inside the workspace document, so it must know which workspace to update. If `workspaceUuid` is undefined in the input it cannot build the `{ uuid: ... }` lookup/update, so it throws before touching the database. This is a deliberate guard against an orphaned or unaddressable status write.

Source

Thrown at server/account/src/collections/mongo.ts:344

  async exists (query: Query<WorkspaceStatus>): Promise<boolean> {
    return await this.wsCollection.exists(this.toWsQuery(query))
  }

  async find (query: Query<WorkspaceStatus>, sort?: Sort<WorkspaceStatus>, limit?: number): Promise<WorkspaceStatus[]> {
    return (await this.wsCollection.find(this.toWsQuery(query), this.toWsSort(sort), limit)).map((ws) => ({
      ...ws.status,
      workspaceUuid: ws.uuid
    }))
  }

  async findOne (query: Query<WorkspaceStatus>): Promise<WorkspaceStatus | null> {
    return (await this.wsCollection.findOne(this.toWsQuery(query)))?.status ?? null
  }

  async insertOne (data: Partial<WorkspaceStatus>): Promise<any> {
    if (data.workspaceUuid === undefined) {
      throw new Error('workspaceUuid is required')
    }

    const wsData = await this.wsCollection.findOne({ uuid: data.workspaceUuid })

    if (wsData === null) {
      throw new Error(`Workspace with uuid ${data.workspaceUuid} not found`)
    }

    const statusData: any = {}

    for (const key of Object.keys(data)) {
      if (key !== 'workspaceUuid') {
        statusData[`status.${key}`] = (data as any)[key]
      }
    }

    await this.wsCollection.update({ uuid: data.workspaceUuid }, statusData)

View on GitHub (pinned to 63e28dc964)

Solutions

1. Always include a valid `workspaceUuid` in the object passed to insertOne.
2. Create/obtain the workspace first and use its returned uuid for the status insert.
3. Verify variable naming at the call site — a typo like `workspaceId` instead of `workspaceUuid` silently yields undefined.
4. Guard with an early check in the caller and return a clear client-facing validation error.

Example fix

// before
await workspaceStatus.insertOne({ active: true })
// after
await workspaceStatus.insertOne({ workspaceUuid: wsUuid, active: true })

function canInsertWorkspaceStatus(data) {
  return data != null && typeof data.workspaceUuid === 'string' && data.workspaceUuid.length > 0
}

function hasWorkspaceUuid(d: Partial<WorkspaceStatus> | null | undefined): d is { workspaceUuid: WorkspaceUuid } & Partial<WorkspaceStatus> {
  return d !== null && d !== undefined && (d as any).workspaceUuid !== undefined
}

try {
  await workspaceStatus.insertOne(data)
} catch (err) {
  if (err instanceof Error && err.message === 'workspaceUuid is required') {
    throw new BadRequestError('workspaceUuid is required to set workspace status')
  }
  throw err
}

When it happens

Trigger: Calling workspaceStatus.insertOne with an object lacking `workspaceUuid` — e.g. { active: true, name: 'ws' } — or passing `{ workspaceUuid: undefined }` after destructuring from a failed lookup. Any caller forwarding a Partial<WorkspaceStatus> built without first obtaining a workspace uuid.

Common situations: A workspace-create flow reading the generated uuid from a variable that is undefined because workspace creation failed or the wrong property was read; copying status objects from query results where `workspaceUuid` was mapped out; test fixtures seeding status without the uuid field.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

• Type and value are required
• Failed to load server config
• getDisplayMedia not supported
• No screen access granted
• Message id is required

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