What causes "Workspace not found" in hcengineering/platform?

Verify the workspace name/identifier matches an existing workspace for that account.

hcengineering/platform · error · Error

Workspace not found

Error message

Workspace not found

What it means

After successful authentication, getWorkspaceToken calls selectWorkspace to find the requested workspace for the account. If the accounts service returns no matching workspace, it throws 'Workspace not found'. Authentication succeeded but the account has no access to (or does not have) that workspace.

Source

Thrown at foundations/core/packages/api-client/src/utils.ts:51

  config ??= await loadServerConfig(url)

  let token: string | undefined

  if ('token' in options) {
    token = options.token
  } else {
    const { email, password } = options
    const loginInfo = await getAccountClient(config.ACCOUNTS_URL).login(email, password)
    token = loginInfo.token
  }

  if (token === undefined) {
    throw new Error('Login failed')
  }

  const ws = await getAccountClient(config.ACCOUNTS_URL, token).selectWorkspace(options.workspace)
  if (ws === undefined) {
    throw new Error('Workspace not found')
  }

  return { endpoint: ws.endpoint, token: ws.token, workspaceId: ws.workspace, info: ws }
}

View on GitHub (pinned to 63e28dc964)

Solutions

Verify the workspace name/identifier matches an existing workspace for that account.
Confirm the account is still a member of the target workspace.
Check you are pointing at the correct deployment's ACCOUNTS_URL.
List the account's workspaces (via the account client) to see valid names.
Handle the error in onboarding flows to prompt the user to pick a valid workspace.

Example fix

// before
const conn = await connect(token, workspace)
// after
const ws = await getAccountClient(config.ACCOUNTS_URL, token).selectWorkspace(workspace)
if (ws === undefined) {
  throw new Error(`Workspace "${workspace}" not found for this account`)
}
const conn = await connect(token, workspace)

Defensive patterns

Strategy: validation

Validate before calling

const wsList = await getAccountClient(config.ACCOUNTS_URL, token).listWorkspaces(account)
if (!wsList.some(w => w.name === workspace)) {
  throw new Error(`Workspace "${workspace}" not available for this account`)
}

Type guard

function workspaceExists(ws: { name: string }[] | undefined, name: string): ws is { name: string }[] {
  return ws?.some(w => w.name === name) === true
}

Try / catch

try {
  const { token, endpoint } = await getWorkspaceToken(opts)
} catch (err) {
  if (err.message === 'Workspace not found') {
    console.error(`Workspace "${opts.workspace}" missing — check name/membership`)
    throw err
  }
  throw err
}

Prevention

List the account's workspaces and validate the target name before connecting
Confirm workspace names per environment (dev vs prod)
Check membership after workspace invites/removals
Present a workspace picker on this error instead of failing hard

When it happens

Trigger: getWorkspaceToken called with options.workspace naming a workspace that does not exist, was renamed/deleted, or the authenticated account is not a member of.

Common situations: Typo in workspace name/URL in config or env; user removed from the workspace; workspace deleted; connecting against the wrong deployment (e.g. prod workspace name on dev accounts service).

Related errors

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