What causes "documentName must include workspace id" in hcengineering/platform?

Verify the document name embeds the same workspace uuid the token was issued for.

documentName must include workspace id

Error message

documentName must include workspace id

What it means

During Hocuspocus authentication, onAuthenticate extracts the workspace id from the document name, fetches the workspace ids allowed for the token via getWorkspaceIds(data.token), and compares them. If ids.uuid !== workspaceId it throws this error, meaning the token is not authorized for the workspace encoded in the document name (or the document name is malformed).

Source

Thrown at server/collaborator/src/extensions/authentication.ts:63

        const readonly = isReadOnlyOrGuest(token.account, token.extra)

        ctx.info('authenticate', {
          workspaceId,
          account: token.account,
          mode: token.extra?.mode ?? '',
          readonly
        })

        if (readonly) {
          data.connection.readOnly = true
        }

        // verify workspace can be accessed with the token
        const ids = await getWorkspaceIds(data.token)

        // verify workspace uuid in the document matches the token
        if (ids.uuid !== workspaceId) {
          throw new Error('documentName must include workspace id')
        }

        return buildContext(data, ids)
      },
      { workspaceId }
    )
  }
}

View on GitHub (pinned to 63e28dc964)

Solutions

Verify the document name embeds the same workspace uuid the token was issued for.
Re-acquire the token for the correct workspace (token may be from another tenant or expired-and-reissued for a different uuid).
Check getWorkspaceIds/token issuer config to ensure the right workspace is associated with the account.
If workspace ids changed (migration/rename), regenerate document names and tokens from the current workspace record.

Example fix

// before
const docName = `${oldWorkspaceId}:${docId}` // stale id
provider = new HocuspocusProvider({ name: docName, token })

// after
const docName = `${currentWorkspace.uuid}:${docId}`
if (!docName.startsWith(currentWorkspace.uuid)) {
  throw new Error('document name workspace id mismatch with token')
}
provider = new HocuspocusProvider({ name: docName, token })

Defensive patterns

Strategy: validation

Validate before calling

function documentNameFor (workspaceUuid: string, docId: string): string {
  const name = `${workspaceUuid}:${docId}`
  if (!name.startsWith(workspaceUuid)) throw new Error('documentName must include workspace id')
  return name
}
// client: ensure token and workspaceUuid come from the same auth response

Type guard

function hasMatchingWorkspace (docName: string, tokenWorkspaceUuid: string): boolean {
  return typeof docName === 'string' && docName.startsWith(`${tokenWorkspaceUuid}:`)
}

Try / catch

try {
  await connectProvider(documentName, token)
} catch (err) {
  if (err.message.includes('documentName must include workspace id')) {
    console.error('Token/workspace mismatch: re-authenticate for workspace', documentName.split(':')[0])
    await refreshTokenForWorkspace(workspaceId)
  } else {
    throw err
  }
}

Prevention

Always derive documentName's workspace prefix from the same auth payload that issued the token.
Never hardcode or cache workspace ids across environments or tenants.
After workspace migration/rename, reissue both tokens and document names together.
Validate document name format client-side before opening a provider connection.

When it happens

Trigger: Connecting a collaboration client with a documentName whose embedded workspace uuid does not match the token's workspace; using a token issued for workspace A on a document of workspace B; or passing a documentName without the expected '<workspaceId>...' format.

Common situations: Hardcoded or cached document names from another environment, stale tokens after a workspace migration, multi-tenant frontends mixing workspace ids, or tests reusing a document name from a different account.

Related errors

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