What causes "Invalid workspace: \n${errors}" in hcengineering/platform?

Read the per-path error list in the message and fix each underlying data problem (duplicates, invalid fields, dangling references).

hcengineering/platform · error · Error

Invalid workspace: \n${errors}

Error message

Invalid workspace: \n${errors}

What it means

WorkspaceBuilder.build() first runs validate(); in strictMode, if any validation errors were collected (duplicate issue numbers, invalid entities, broken references, etc.), it refuses to produce the ImportWorkspace and throws a single aggregated 'Invalid workspace' error listing every error path and message.

Source

Thrown at packages/importer/src/importer/builder.ts:231

    return this
  }

  validate (): ValidationResult {
    // Perform cross-entity validation
    this.validateSpacesReferences()
    this.validateDocumentsReferences()

    return {
      isValid: this.errors.size === 0,
      errors: this.errors
    }
  }

  build (): ImportWorkspace {
    const validation = this.validate()
    if (this.strictMode && !validation.isValid) {
      throw new Error(
        'Invalid workspace: \n' +
          Array.from(validation.errors.values())
            .map((e) => `    * ${e.path}: ${e.error}`)
            .join(';\n')
      )
    }

    for (const [teamspacePath, docs] of this.documentsByTeamspace) {
      const teamspace = this.teamspaces.get(teamspacePath)
      if (teamspace !== undefined) {
        const rootDocPaths = Array.from(docs.keys()).filter((docPath) => !this.documentParents.has(docPath))

        for (const rootPath of rootDocPaths) {
          this.buildDocumentHierarchy(rootPath, docs)
        }

        teamspace.docs = rootDocPaths.map((path) => docs.get(path)).filter(Boolean) as ImportDocument[]
      }

View on GitHub (pinned to 63e28dc964)

Solutions

Read the per-path error list in the message and fix each underlying data problem (duplicates, invalid fields, dangling references).
Re-run build() after corrections; iterate until validation passes.
If appropriate for your use case, disable strictMode (set builder strictMode=false) so build() proceeds and errors are reported as warnings instead of throwing.
Add pre-import validation on your source data to catch duplicates and broken references before calling add*.

Example fix

// before
const builder = new WorkspaceBuilder({ strictMode: true })
builder.build() // throws on any collected error
// after — inspect non-strict results
const builder = new WorkspaceBuilder({ strictMode: false })
const ws = builder.build()
const { isValid, errors } = builder.validate()
if (!isValid) console.log([...errors.values()])

Defensive patterns

Strategy: try-catch

Validate before calling

const validation = builder.validate()
if (!validation.isValid) {
  for (const e of validation.errors.values()) console.error(`${e.path}: ${e.error}`)
  throw new Error('Fix validation errors before build()')
}

Try / catch

try {
  const workspace = builder.build()
} catch (e) {
  if ((e as Error).message.startsWith('Invalid workspace:')) {
    // parse bulleted entries 'path: error' and fix each before rebuilding
    console.error((e as Error).message)
  } else throw e
}

Prevention

Call validate() before build() and fix all reported paths first.
Use strictMode=false during data cleanup to collect all errors at once, then re-enable for production imports.
Pre-validate source data (duplicates, required fields, references) before feeding the builder.
Treat the bulleted error list as a checklist; each entry maps to a specific data file/path.

When it happens

Trigger: Calling build() while strictMode is enabled and validate() returns isValid=false — i.e. any addError was recorded during add* calls or cross-entity reference validation (validateSpacesReferences, validateDocumentsReferences).

Common situations: Import data with dangling parent/space references; duplicate issue numbers in a project; malformed entities added via add* methods; enabling strict mode on legacy data that has known minor issues.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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