{"record":{"id":"9be36ded3c2bdd7c","repo":"hcengineering/platform","slug":"template-file-not-found-templatepath","errorCode":null,"errorMessage":"Template file not found: ${templatePath}","messagePattern":"Template file not found: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/importer/src/huly/huly.ts","lineNumber":793,"sourceCode":"  }\n\n  private async processControlledDocument (\n    header: HulyControlledDocumentHeader,\n    docPath: string,\n    id: Ref<ControlledDocument>,\n    metaId: Ref<DocumentMeta>\n  ): Promise<ImportControlledDocument> {\n    const codeMatch = path.basename(docPath).match(/^\\[([^\\]]+)\\]/)\n\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 templatePath = path.resolve(path.dirname(docPath), header.template)\n    if (!fs.existsSync(templatePath)) {\n      throw new Error(`Template file not found: ${templatePath}`)\n    }\n\n    const templateId = this.metadataRegistry.getRef(templatePath) as Ref<ControlledDocument>\n    const category = header.category !== undefined ? this.controlledDocumentCategories.get(header.category) : undefined\n    return {\n      id,\n      metaId,\n      class: documents.class.ControlledDocument,\n      title: header.title,\n      template: templateId,\n      code: codeMatch?.[1],\n      major: 0,\n      minor: 1,\n      state: DocumentState.Draft,\n      category,\n      author,\n      owner,\n      abstract: header.abstract,","sourceCodeStart":775,"sourceCodeEnd":811,"githubUrl":"https://github.com/hcengineering/platform/blob/63e28dc96483967b2fc21c881b3f1023c1de7718/packages/importer/src/huly/huly.ts#L775-L811","documentation":"HulyFormatImporter.processControlledDocument resolves the controlled document's template relative to the document's directory (path.resolve(dirname(docPath), header.template)). If the resolved file does not exist on disk, the importer throws this error because a ControlledDocument cannot be created without a valid template reference (templateId comes from metadataRegistry.getRef of that file).","triggerScenarios":"Importing a Huly controlled-document markdown file whose YAML header contains a `template` value pointing to a file that does not exist relative to the document's directory: fs.existsSync(templatePath) is false at huly.ts:792.","commonSituations":"Typo in the template path in the YAML header; template file moved/renamed/deleted; using an absolute path or wrong relative path in `template:`; importing a partial export where the templates directory was not copied; case-sensitive filesystem where 'Templates/Doc.md' vs 'templates/doc.md' matters.","solutions":["Check the `template:` value in the document's YAML header and fix it to point to the actual template file relative to the document's directory.","Verify the resolved path exists on disk (ls the resolved path printed in the error message); create or restore the missing template file if the export was incomplete.","Ensure the template file itself is included in the import set so the metadata registry can assign it a ref.","On case-sensitive filesystems, fix the casing of the path to match the actual file."],"exampleFix":"// before (doc header)\ntemplate: ../templates/quality-manual.md\n// after (file actually lives in ../Templates)\ntemplate: ../Templates/quality-manual.md","handlingStrategy":"validation","validationCode":"const templatePath = path.resolve(path.dirname(docPath), header.template)\nif (!fs.existsSync(templatePath)) {\n  throw new Error(`Header template '${header.template}' does not exist (resolved: ${templatePath})`)\n}","typeGuard":null,"tryCatchPattern":"try {\n  await importer.importFile(docPath)\n} catch (e) {\n  if ((e as Error).message.startsWith('Template file not found:')) {\n    console.error(`Bad template reference in ${docPath}: ${e.message}`)\n  } else throw e\n}","preventionTips":["Keep template files in the same directory tree as the documents that reference them and use paths relative to the document.","Pre-commit script: parse each controlled document's YAML header and assert the resolved template path exists.","Never hand-edit the `template:` value without re-checking the relative base directory.","On Linux/macOS remember paths are case-sensitive; match casing exactly."],"tags":["importer","file-not-found","huly","controlled-document"],"backgroundTag":"file-not-found","analyzedSha":"63e28dc96483967b2fc21c881b3f1023c1de7718","analyzedAt":"2026-08-29T15:21:27.377Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}