hcengineering/platform · error

Unknown document class ${docHeader.class} in ${docFile}

Error message

Unknown document class ${docHeader.class} in ${docFile}

What it means

processDocumentsRecursively walks a Teamspace's markdown files and dispatches on each file's front-matter `class`. Only recognized document classes are importable; a file declaring a different class cannot be mapped and throws. Files without a class are skipped with a log, so this error specifically means a declared-but-unknown class.

Source

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

        this.metadataRegistry.setRefMetadata(docPath, document.class.Document, docHeader.title)

        const doc: ImportDocument = {
          id: this.metadataRegistry.getRef(docPath) as Ref<Document>,
          class: document.class.Document,
          title: docHeader.title,
          descrProvider: () => Promise.resolve(this.parser.readMarkdownContent(docPath)),
          subdocs: [] // Will be added via builder
        }

        builder.addDocument(teamspacePath, docPath, doc, parentDocPath)

        // Process subdocuments if they exist
        const subDir = path.join(currentPath, docFile.replace('.md', ''))
        if (fs.existsSync(subDir) && fs.statSync(subDir).isDirectory()) {
          await this.processDocumentsRecursively(builder, teamspacePath, subDir, docPath)
        }
      } else {
        throw new Error(`Unknown document class ${docHeader.class} in ${docFile}`)
      }
    }
  }

  private async processControlledDocumentsRecursively (
    builder: ImportWorkspaceBuilder,
    spacePath: string,
    currentPath: string,
    parentDocPath?: string
  ): Promise<void> {
    const docFiles = fs.readdirSync(currentPath).filter((f) => f.endsWith('.md'))

    for (const docFile of docFiles) {
      const docPath = path.join(currentPath, docFile)
      const docHeader = this.parser.readYamlHeader(docPath) as HulyControlledDocumentHeader | HulyDocumentTemplateHeader

      if (docHeader.class === undefined) {
        this.logger.error(`Skipping ${docFile}: not a document`)

View on GitHub (pinned to 63e28dc964)

Solutions

1. Inspect the `class:` front-matter field of the reported docFile
2. Set it to the document class supported by Teamspaces (matching the exporter's exact identifier)
3. Move controlled-document files into the OrgSpace folder instead of the Teamspace
4. Re-export from Huly so document classes match the importer version

Example fix

// before (doc md front-matter)
class: documents.class.Page
// after
class: documents.class.Document

for (const f of fs.readdirSync(teamspaceDir).filter(f => f.endsWith('.md'))) {
  const h = readYamlHeader(path.join(teamspaceDir, f))
  if (h?.class !== undefined && h.class !== expectedTeamspaceDocClass) {
    throw new Error(`${f}: unexpected class ${h.class} in teamspace`)
  }
}

function isTeamspaceDoc(h: unknown): boolean {
  return typeof h === 'object' && h !== null && (h as any).class === 'documents.class.Document'
}

try {
  await importer.workspaceData(folder)
} catch (e) {
  if (e instanceof Error && e.message.includes('Unknown document class')) {
    console.error('Fix the `class:` front-matter of the reported file:', e.message)
  } else throw e
}

When it happens

Trigger: processImportFolder → processDocumentsRecursively reads a .md file in a Teamspace folder whose front-matter `class:` is neither documents' recognized teamspace document class nor undefined — a typo, foreign class id, or version-mismatched identifier.

Common situations: Hand-written document files with an incorrect class; copying markdown from controlled-document (OrgSpace) areas into a Teamspace; importer/exporter version mismatch changing class identifiers.

Related errors

• Unknown issue class ${issueHeader.class} in ${issueFile}
• Unknown space class ${spaceConfig.class} in ${spaceName}
• 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/1fedb8b7cde61a5e. Report an issue: GitHub.