hcengineering/platform · error · TokenError

Invalid account uuid: "${accountUuid}"

Error message

Invalid account uuid: "${accountUuid}"

What it means

generateToken validates the accountUuid with a UUID validator before signing a token. If the string is not a valid UUID it throws a TokenError rather than embedding an invalid subject into a signed token.

Source

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

}

/**
 * @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 }
  }

View on GitHub (pinned to 63e28dc964)

Solutions

1. Validate the accountUuid with a UUID validator (e.g. crypto's validate) before calling generateToken
2. Fix the source of the id — check env/config/lookup actually produced a UUID
3. Log/inspect the offending value; verify it is not truncated or wrapped in quotes

Example fix

// before
const t = generateToken(process.env.ACCOUNT as string, workspaceUuid, ...)
// after
const account = process.env.ACCOUNT ?? ''
if (!validate(account)) throw new Error('ACCOUNT env must be a uuid')
const t = generateToken(account, workspaceUuid, ...)

import { validate } from '@tooee/uuid' // or your uuid lib
if (typeof accountUuid !== 'string' || !validate(accountUuid)) {
  throw new Error('accountUuid must be a valid UUID')
}

const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
function isUuid(v: unknown): v is string {
  return typeof v === 'string' && UUID_RE.test(v)
}

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

When it happens

Trigger: Calling generateToken (directly or via token/config/githubToken/gmailToken/devTool helpers) with an accountUuid that is undefined, empty, malformed, or not a canonical UUID string.

Common situations: Config values read from env vars or CLI args passed unvalidated, test fixtures with placeholder strings, IDs fetched from external systems that are not UUIDs.

Related errors

• Invalid workspace uuid: "${workspaceUuid}"
• 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/96b23cf686b26aa5. Report an issue: GitHub.