What causes "Teamspace ${teamspacePath} not found" in hcengineering/platform?

Register the teamspace with addTeamspace(teamspacePath, ...) before adding documents under it.

hcengineering/platform · error · Error

Teamspace not found

Error message

Teamspace ${teamspacePath} not found

What it means

WorkspaceBuilder.addDocument keeps documents per teamspace in this.documentsByTeamspace and lazily creates the inner Map. The get() immediately after returning undefined triggers 'Teamspace <path> not found'. Like the issue variant, this is a defensive invariant that should be unreachable in sequential use since addDocument creates the entry when missing.

Solutions

Register the teamspace with addTeamspace(teamspacePath, ...) before adding documents under it.
Avoid concurrent or out-of-order calls into a single WorkspaceBuilder instance.
Audit any code that mutates or clones the builder's internal maps during processing.
If reproducible in plain sequential code, report as a bug.

Example fix

// before
builder.addDocument('ts/main', docPath, doc)
// after
builder.addTeamspace('ts/main', teamspace)
builder.addDocument('ts/main', docPath, doc)

Defensive patterns

Strategy: try-catch

Validate before calling

if (!builder.getTeamspaces().has(teamspacePath)) {
  builder.addTeamspace(teamspacePath, teamspace)
}

Try / catch

try {
  builder.addDocument(teamspacePath, docPath, doc)
} catch (e) {
  if ((e as Error).message === `Teamspace ${teamspacePath} not found`) {
    console.error(`Builder state lost for teamspace ${teamspacePath}; re-add the teamspace first`)
  } else throw e
}

Prevention

Register teamspaces with addTeamspace before adding their documents.
Keep builder calls sequential; avoid sharing the builder between async workers.
Do not mutate internal maps from outside the class.
On this error, restart the build rather than retrying the single call.

When it happens

Trigger: addDocument called when the documentsByTeamspace entry for teamspacePath is removed/corrupted between has/set and get — e.g. external mutation of builder state, concurrency, or a subclass interfering.

Common situations: Running document processing concurrently against one builder; resetting builder internals mid-run; copying the builder object and operating on a stale shallow copy.

Related errors

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

Appendix: source

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

      this.addError(issuePath, `Duplicate issue number ${issue.number} in project ${projectPath}`)
    } else {
      this.validateAndAdd('issue', issuePath, issue, (i) => this.validateIssue(i), projectIssues, issuePath)

      if (parentIssuePath !== undefined) {
        this.issueParents.set(issuePath, parentIssuePath)
      }
    }
    return this
  }

  addDocument (teamspacePath: string, docPath: string, doc: ImportDocument, parentDocPath?: string): this {
    if (!this.documentsByTeamspace.has(teamspacePath)) {
      this.documentsByTeamspace.set(teamspacePath, new Map())
    }

    const docs = this.documentsByTeamspace.get(teamspacePath)
    if (docs === undefined) {
      throw new Error(`Teamspace ${teamspacePath} not found`)
    }

    this.validateAndAdd('document', docPath, doc, (d) => this.validateDocument(d), docs, docPath)

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

    return this
  }

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

  addControlledDocument (
    spacePath: string,

View on GitHub (pinned to 63e28dc964)