{"record":{"id":"5941e772e9459111","repo":"hcengineering/platform","slug":"category-not-found-header-category","errorCode":null,"errorMessage":"Category not found: ${header.category}","messagePattern":"Category not found: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/importer/src/huly/huly.ts","lineNumber":837,"sourceCode":"      subdocs: []\n    }\n  }\n\n  private async processControlledDocumentTemplate (\n    header: HulyDocumentTemplateHeader,\n    docPath: string,\n    id: Ref<ControlledDocument>,\n    metaId: Ref<DocumentMeta>\n  ): Promise<ImportControlledDocumentTemplate> {\n    const author = this.findEmployeeByName(header.author)\n    const owner = this.findEmployeeByName(header.owner)\n    if (author === undefined || owner === undefined) {\n      throw new Error(`Author or owner not found: ${header.author} or ${header.owner}`)\n    }\n\n    const category = this.controlledDocumentCategories.get(header.category)\n    if (category === undefined) {\n      throw new Error(`Category not found: ${header.category}`)\n    }\n\n    const codeMatch = path.basename(docPath).match(/^\\[([^\\]]+)\\]/)\n    return {\n      id,\n      metaId,\n      class: documents.mixin.DocumentTemplate,\n      title: header.title,\n      docPrefix: header.docPrefix,\n      code: codeMatch?.[1],\n      major: 0,\n      minor: 1,\n      state: DocumentState.Draft,\n      category,\n      author,\n      owner,\n      abstract: header.abstract,\n      reviewers: header.reviewers?.map((name) => this.findEmployeeByName(name)) ?? [],","sourceCodeStart":819,"sourceCodeEnd":855,"githubUrl":"https://github.com/hcengineering/platform/blob/63e28dc96483967b2fc21c881b3f1023c1de7718/packages/importer/src/huly/huly.ts#L819-L855","documentation":"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.)","triggerScenarios":"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.","commonSituations":"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.","solutions":["Fix the `category:` value in the template header to exactly match a category defined in the workspace import data.","Include/import the file that defines the category before importing templates that reference it.","If the category was renamed, update all template headers referencing the old name.","Normalize casing/whitespace in the category name."],"exampleFix":"// before\ncategory: Quality Manuals\n// after (workspace defines 'quality')\ncategory: quality","handlingStrategy":"validation","validationCode":"// before import: check template categories against known categories\nif (!knownCategories.has(header.category)) {\n  throw new Error(`Unknown category '${header.category}' in ${docPath}`)\n}","typeGuard":null,"tryCatchPattern":"try {\n  await importer.importFile(tplPath)\n} catch (e) {\n  if ((e as Error).message.startsWith('Category not found:')) {\n    console.error(`Define or fix category in ${tplPath}: ${e.message}`)\n  } else throw e\n}","preventionTips":["Maintain a single source of truth for category names and reference it when writing headers.","Import category-definition files before templates that use them.","Lint YAML headers against the category list in CI.","When renaming a category, grep and update all template headers."],"tags":["importer","huly","category","controlled-document-template"],"backgroundTag":"referenced-entity-not-found","analyzedSha":"63e28dc96483967b2fc21c881b3f1023c1de7718","analyzedAt":"2026-08-29T15:21:27.377Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}