What causes "Template file not found: ${templatePath}" in hcengineering/platform?

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.

hcengineering/platform · error

Template file not found: ${templatePath}

Error message

Template file not found: ${templatePath}

What it means

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).

Source

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

  }

  private async processControlledDocument (
    header: HulyControlledDocumentHeader,
    docPath: string,
    id: Ref<ControlledDocument>,
    metaId: Ref<DocumentMeta>
  ): Promise<ImportControlledDocument> {
    const codeMatch = path.basename(docPath).match(/^\[([^\]]+)\]/)

    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 templatePath = path.resolve(path.dirname(docPath), header.template)
    if (!fs.existsSync(templatePath)) {
      throw new Error(`Template file not found: ${templatePath}`)
    }

    const templateId = this.metadataRegistry.getRef(templatePath) as Ref<ControlledDocument>
    const category = header.category !== undefined ? this.controlledDocumentCategories.get(header.category) : undefined
    return {
      id,
      metaId,
      class: documents.class.ControlledDocument,
      title: header.title,
      template: templateId,
      code: codeMatch?.[1],
      major: 0,
      minor: 1,
      state: DocumentState.Draft,
      category,
      author,
      owner,
      abstract: header.abstract,

View on GitHub (pinned to 63e28dc964)

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.

Example fix

// before (doc header)
template: ../templates/quality-manual.md
// after (file actually lives in ../Templates)
template: ../Templates/quality-manual.md

Defensive patterns

Strategy: validation

Validate before calling

const templatePath = path.resolve(path.dirname(docPath), header.template)
if (!fs.existsSync(templatePath)) {
  throw new Error(`Header template '${header.template}' does not exist (resolved: ${templatePath})`)
}

Try / catch

try {
  await importer.importFile(docPath)
} catch (e) {
  if ((e as Error).message.startsWith('Template file not found:')) {
    console.error(`Bad template reference in ${docPath}: ${e.message}`)
  } else throw e
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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