hcengineering/platform · error · TokenError

Invalid workspace uuid: "${workspaceUuid}"

Error message

Invalid workspace uuid: "${workspaceUuid}"

What it means

generateToken validates workspaceUuid only if provided, but a provided value that is not a valid UUID is rejected with a TokenError to prevent signing tokens with malformed workspace scoping.

Source

Thrown at foundations/core/packages/token/src/token.ts:71

 * @public
 */
export function generateToken (
  accountUuid: PersonUuid,
  workspaceUuid?: WorkspaceUuid,
  extra?: Record<string, string>,
  secret?: string,
  options?: {
    grant?: PermissionsGrant
    nbf?: number
    exp?: number
    sub?: PersonUuid
  }
): string {
  if (!validate(accountUuid)) {
    throw new TokenError(`Invalid account uuid: "${accountUuid}"`)
  }
  if (workspaceUuid !== undefined && !validate(workspaceUuid)) {
    throw new TokenError(`Invalid workspace uuid: "${workspaceUuid}"`)
  }
  const { grant, nbf, exp, sub } = options ?? {}
  if (grant?.workspace !== undefined && !validate(grant?.workspace)) {
    throw new TokenError(`Invalid grant workspace uuid: "${grant?.workspace}"`)
  }

  if (grant != null && sub == null && (nbf == null || exp == null)) {
    throw new TokenError('nbf and exp are required when sub is not provided')
  }

  const service = getMetadata(serverPlugin.metadata.Service)
  if (service !== undefined) {
    extra = { service, ...extra }
  }

  const sanitizedGrant: PermissionsGrant | undefined =
    grant !== undefined
      ? {

View on GitHub (pinned to 63e28dc964)

Solutions

1. Validate workspaceUuid with a UUID validator before calling generateToken
2. Ensure the value comes from a trusted source that emits canonical UUIDs
3. Check argument order — account and workspace uuids are easy to swap

Example fix

// before
generateToken(accountUuid, req.params.workspace, ...)
// after
const ws = req.params.workspace
if (!validate(ws)) return res.status(400).send('invalid workspace id')
generateToken(accountUuid, ws, ...)

if (workspaceUuid !== undefined && !isUuid(workspaceUuid)) {
  throw new Error('workspaceUuid must be a valid UUID when provided')
}

function isUuidOrUndefined(v: unknown): v is string | undefined {
  return v === undefined || (typeof v === 'string' && UUID_RE.test(v))
}

try {
  const token = generateToken(accountUuid, workspaceUuid, opts)
} catch (e) {
  if (e instanceof TokenError && e.message.includes('Invalid workspace uuid')) {
    throw new ConfigError(`workspace id "${workspaceUuid}" is not a uuid`)
  }
  throw e
}

When it happens

Trigger: Calling generateToken with a workspaceUuid that is present but malformed — wrong length, non-hex characters, missing dashes, or a non-string value.

Common situations: Workspace ids taken from URL path segments, CSV/fixture data, or user input; config mistakes where an account uuid is pasted into the workspace slot.

Related errors

• Invalid account uuid: "${accountUuid}"
• Invalid grant workspace uuid: "${grant?.workspace}"
• nbf and exp are required when sub is not provided
• Workspace or account not found in token
• Failed to load server config

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