hcengineering/platform · error · Error

Document space ${spacePath} not found

Error message

Document space ${spacePath} not found

What it means

WorkspaceBuilder.addControlledDocument stores controlled documents per QMS space in this.qmsDocsBySpace, creating the inner Map if absent, then throws 'Document space <path> not found' if get() still returns undefined. This is a defensive invariant; in sequential use the entry is created on the same call, so the throw indicates corrupted or concurrently mutated builder state.

Source

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

  addOrgSpace (path: string, space: ImportOrgSpace): this {
    this.validateAndAdd('documentSpace', path, space, (s) => this.validateOrgSpace(s), this.qmsSpaces, path)
    return this
  }

  addControlledDocument (
    spacePath: string,
    docPath: string,
    doc: ImportControlledDocument,
    parentDocPath?: string
  ): this {
    if (!this.qmsDocsBySpace.has(spacePath)) {
      this.qmsDocsBySpace.set(spacePath, new Map())
    }

    const docs = this.qmsDocsBySpace.get(spacePath)
    if (docs === undefined) {
      throw new Error(`Document space ${spacePath} not found`)
    }

    this.validateAndAdd(
      'controlledDocument',
      docPath,
      doc,
      (d) => this.validateControlledDocument(d as ImportControlledDocument),
      docs,
      docPath
    )

    if (parentDocPath !== undefined) {
      this.qmsDocsParents.set(docPath, parentDocPath)
    }

    return this
  }

View on GitHub (pinned to 63e28dc964)

Solutions

1. Register the space first with addOrgSpace(spacePath, space) so document processing has a well-defined order.
2. Keep builder usage single-threaded / sequential per import run.
3. Remove any mid-run clearing or replacement of the builder's internal maps.
4. Report as a bug if it fires in plain sequential usage.

Example fix

// before
builder.addControlledDocument('space/qms', docPath, doc)
// after
builder.addOrgSpace('space/qms', orgSpace)
builder.addControlledDocument('space/qms', docPath, doc)

if (!builder.getOrgSpaces().has(spacePath)) {
  builder.addOrgSpace(spacePath, orgSpace)
}

try {
  builder.addControlledDocument(spacePath, docPath, doc)
} catch (e) {
  if ((e as Error).message === `Document space ${spacePath} not found`) {
    console.error(`Builder state lost for space ${spacePath}; re-add the org space first`)
  } else throw e
}

When it happens

Trigger: addControlledDocument invoked while the qmsDocsBySpace entry for spacePath is externally removed, or builder state is mutated concurrently between the set and get calls.

Common situations: Parallel import pipelines sharing one builder; code that clears qmsDocsBySpace to re-run import; subclasses overriding map lifecycle.

Related errors

• Project ${projectPath} not found
• Teamspace ${teamspacePath} not found
• Invalid workspace: \n${errors}
• Invalid ${type} at ${path}: \n${errors.map((e) => ` * ${e
• update is null

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