hcengineering/platform · error

WorkspaceUuid is not defined

Error message

WorkspaceUuid is not defined

What it means

In the presentation package, `getClient` reads the WorkspaceUuid from plugin metadata and throws this Error when it is undefined. The CollaboratorClient requires a workspace UUID to connect, so collaboration cannot be set up without it. This guards against running presentation code in a context where the platform never injected the workspace metadata.

Source

Thrown at packages/presentation/src/collaborator.ts:25

//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//
// See the License for the specific language governing permissions and
// limitations under the License.
//

import { type CollaboratorClient, getClient as getCollaborator } from '@hcengineering/collaborator-client'
import { type Blob, type CollaborativeDoc, type Markup, type Ref } from '@hcengineering/core'
import { getMetadata } from '@hcengineering/platform'

import presentation from './plugin'

function getClient (): CollaboratorClient {
  const workspaceUuid = getMetadata(presentation.metadata.WorkspaceUuid)
  if (workspaceUuid === undefined) {
    throw new Error('WorkspaceUuid is not defined')
  }

  const token = getMetadata(presentation.metadata.Token) ?? ''
  const collaboratorURL = getMetadata(presentation.metadata.CollaboratorUrl) ?? ''

  return getCollaborator(workspaceUuid, token, collaboratorURL)
}

/** @public */
export async function getMarkup (doc: CollaborativeDoc, source: Ref<Blob> | null | undefined): Promise<Markup> {
  const client = getClient()
  return await client.getMarkup(doc, source)
}

/** @public */
export async function createMarkup (doc: CollaborativeDoc, markup: Markup): Promise<Ref<Blob>> {
  const client = getClient()
  return await client.createMarkup(doc, markup)

View on GitHub (pinned to 63e28dc964)

Solutions

1. Ensure the host platform sets the WorkspaceUuid metadata before the presentation plugin initializes.
2. Verify the plugin registration/host version matches what the presentation package expects.
3. Check initialization order — call getClient only after the plugin's metadata has been injected.
4. Add an explicit startup check that logs which metadata keys are present to diagnose the missing value.

Example fix

// before
const collaborator = getClient()
// after
const collaborator = (() => {
  try { return getClient() }
  catch (e) {
    console.error('Collaboration unavailable: workspace metadata missing', e)
    return null
  }
})()

const wsUuid = getMetadata(presentation.metadata.WorkspaceUuid)
if (wsUuid === undefined) {
  throw new Error('Collaboration disabled: host did not provide WorkspaceUuid metadata')
}

function hasWorkspaceUuid(meta: Record<string, unknown>): meta is Record<string, string> {
  return typeof meta[presentation.metadata.WorkspaceUuid as string] === 'string'
}

let client: CollaboratorClient | null = null
try {
  client = getClient()
} catch (e) {
  if ((e as Error).message === 'WorkspaceUuid is not defined') {
    console.warn('Collaboration unavailable outside host environment')
  } else throw e
}

When it happens

Trigger: Calling `getClient()` (directly or via `client`) when `getMetadata(presentation.metadata.WorkspaceUuid)` returns undefined — the metadata was never set by the host platform/plugin environment.

Common situations: Running the presentation outside the host application that supplies metadata, an older host version that doesn't set WorkspaceUuid, a typo/renamed metadata key, or plugin initialization order where metadata isn't populated yet.

Related errors

• Calendar service URL or token is not defined
• Accounts URL or token is not defined
• Accounts URL or token is not defined
• Accounts URL or token is not defined
• No screen access granted

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