hcengineering/platform · error · Error

Workspace ${options.workspace} not found

Error message

Workspace ${options.workspace} not found

What it means

connect() resolves a workspace by name via the accounts service (accountClient.selectWorkspace(options.workspace)). If the accounts service returns no login info for that workspace name, connect throws this Error. It means the named workspace does not exist for the authenticated account (or the account cannot see it).

Source

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

  MarkupContent,
  createMarkupOperations
} from './markup'
import { type ConnectOptions, type PlatformClient, WithMarkup } from './types'
import { getWorkspaceToken } from './utils'

/**
 * Create platform client
 * @public */
export async function connect (url: string, options: ConnectOptions): Promise<PlatformClient> {
  const config = await loadServerConfig(url)

  const { endpoint, token } = await getWorkspaceToken(url, options, config)
  const accountClient = getAccountClient(config.ACCOUNTS_URL, token)
  const socialIds = await accountClient.getSocialIds(true)
  const wsLoginInfo = await accountClient.selectWorkspace(options.workspace)

  if (wsLoginInfo === undefined) {
    throw new Error(`Workspace ${options.workspace} not found`)
  }

  const account: Account = {
    uuid: wsLoginInfo.account,
    role: wsLoginInfo.role,
    primarySocialId: pickPrimarySocialId(socialIds)._id,
    socialIds: socialIds.map((si) => si._id),
    fullSocialIds: socialIds
  }

  return await createClient(url, endpoint, token, wsLoginInfo.workspace, account, config, options)
}

async function createClient (
  url: string,
  endpoint: string,
  token: string,
  workspaceUuid: WorkspaceUuid,

View on GitHub (pinned to 63e28dc964)

Solutions

  1. Verify the workspace name passed in options.workspace matches an existing workspace for that account (check server admin or account workspace list).
  2. Confirm the token used to authenticate belongs to an account with access to the workspace.
  3. Check the environment/config value (env var or connect argument) for typos, whitespace, or case mismatch.
  4. Catch the error and surface a clear message listing valid workspace names.

Example fix

// before
await connect(url, { workspace: process.env.WORKSPACE, token })
// after
const ws = process.env.WORKSPACE?.trim()
if (!ws) throw new Error('WORKSPACE env var is not set')
await connect(url, { workspace: ws, token })
Defensive patterns

Strategy: try-catch

Validate before calling

const ws = options.workspace?.trim()
if (!ws) throw new Error('workspace name is required')

Type guard

function hasWorkspace(o: unknown): o is { workspace: string } {
  return typeof o === 'object' && o !== null && typeof (o as any).workspace === 'string' && (o as any).workspace.length > 0
}

Try / catch

try {
  await connect(url, { workspace, token })
} catch (e) {
  if (e instanceof Error && e.message.includes('not found') && e.message.includes('Workspace')) {
    throw new Error(`Workspace "${workspace}" does not exist or the account has no access; verify the workspace name and token`)
  }
  throw e
}

Prevention

When it happens

Trigger: Calling connect(url, { workspace, ... }) with a workspace name that does not exist, is misspelled, or is not visible to the token's account; selectWorkspace returns undefined and connect throws immediately.

Common situations: Wrong workspace name in env/config (e.g. WORKSPACE env var unset or renamed on the server), connecting with a token from a different account that has no membership in the workspace, typos or case differences in workspace name.

Related errors

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