hcengineering/platform · error · Error

Category not found: ${header.category}

Error message

Category not found: ${header.category}

What it means

In processControlledDocumentTemplate the header.category is looked up in this.controlledDocumentCategories (populated during import of categories). If the category name in the template's YAML header is absent from that map, the importer throws because DocumentTemplate requires a known category. (In processControlledDocument, category is optional and merely left undefined.)

Source

Thrown at packages/importer/src/huly/huly.ts:837

      subdocs: []
    }
  }

  private async processControlledDocumentTemplate (
    header: HulyDocumentTemplateHeader,
    docPath: string,
    id: Ref<ControlledDocument>,
    metaId: Ref<DocumentMeta>
  ): Promise<ImportControlledDocumentTemplate> {
    const author = this.findEmployeeByName(header.author)
    const owner = this.findEmployeeByName(header.owner)
    if (author === undefined || owner === undefined) {
      throw new Error(`Author or owner not found: ${header.author} or ${header.owner}`)
    }

    const category = this.controlledDocumentCategories.get(header.category)
    if (category === undefined) {
      throw new Error(`Category not found: ${header.category}`)
    }

    const codeMatch = path.basename(docPath).match(/^\[([^\]]+)\]/)
    return {
      id,
      metaId,
      class: documents.mixin.DocumentTemplate,
      title: header.title,
      docPrefix: header.docPrefix,
      code: codeMatch?.[1],
      major: 0,
      minor: 1,
      state: DocumentState.Draft,
      category,
      author,
      owner,
      abstract: header.abstract,
      reviewers: header.reviewers?.map((name) => this.findEmployeeByName(name)) ?? [],

View on GitHub (pinned to 63e28dc964)

Solutions

1. Fix the `category:` value in the template header to exactly match a category defined in the workspace import data.
2. Include/import the file that defines the category before importing templates that reference it.
3. If the category was renamed, update all template headers referencing the old name.
4. Normalize casing/whitespace in the category name.

Example fix

// before
category: Quality Manuals
// after (workspace defines 'quality')
category: quality

// before import: check template categories against known categories
if (!knownCategories.has(header.category)) {
  throw new Error(`Unknown category '${header.category}' in ${docPath}`)
}

try {
  await importer.importFile(tplPath)
} catch (e) {
  if ((e as Error).message.startsWith('Category not found:')) {
    console.error(`Define or fix category in ${tplPath}: ${e.message}`)
  } else throw e
}

When it happens

Trigger: Importing a controlled document template whose YAML header `category:` value has no matching entry in controlledDocumentCategories — i.e. the category was never defined/imported or the name differs.

Common situations: Category renamed or removed in the workspace; typo in the category name in the header; category file not included in the import set; case or spacing mismatch between header and category definition.

Related errors

• Template file not found: ${templatePath}
• Tag should be inside master tag folder: ${currentPath}
• Unsupported card type: ${cardType} in ${cardPath}
• Invalid master tag data
• Invalid tag data

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