{"record":{"id":"1fedb8b7cde61a5e","repo":"hcengineering/platform","slug":"unknown-document-class-docheader-class-in-doc","errorCode":null,"errorMessage":"Unknown document class ${docHeader.class} in ${docFile}","messagePattern":"Unknown document class (.+?) in (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/importer/src/huly/huly.ts","lineNumber":600,"sourceCode":"        this.metadataRegistry.setRefMetadata(docPath, document.class.Document, docHeader.title)\n\n        const doc: ImportDocument = {\n          id: this.metadataRegistry.getRef(docPath) as Ref<Document>,\n          class: document.class.Document,\n          title: docHeader.title,\n          descrProvider: () => Promise.resolve(this.parser.readMarkdownContent(docPath)),\n          subdocs: [] // Will be added via builder\n        }\n\n        builder.addDocument(teamspacePath, docPath, doc, parentDocPath)\n\n        // Process subdocuments if they exist\n        const subDir = path.join(currentPath, docFile.replace('.md', ''))\n        if (fs.existsSync(subDir) && fs.statSync(subDir).isDirectory()) {\n          await this.processDocumentsRecursively(builder, teamspacePath, subDir, docPath)\n        }\n      } else {\n        throw new Error(`Unknown document class ${docHeader.class} in ${docFile}`)\n      }\n    }\n  }\n\n  private async processControlledDocumentsRecursively (\n    builder: ImportWorkspaceBuilder,\n    spacePath: string,\n    currentPath: string,\n    parentDocPath?: string\n  ): Promise<void> {\n    const docFiles = fs.readdirSync(currentPath).filter((f) => f.endsWith('.md'))\n\n    for (const docFile of docFiles) {\n      const docPath = path.join(currentPath, docFile)\n      const docHeader = this.parser.readYamlHeader(docPath) as HulyControlledDocumentHeader | HulyDocumentTemplateHeader\n\n      if (docHeader.class === undefined) {\n        this.logger.error(`Skipping ${docFile}: not a document`)","sourceCodeStart":582,"sourceCodeEnd":618,"githubUrl":"https://github.com/hcengineering/platform/blob/63e28dc96483967b2fc21c881b3f1023c1de7718/packages/importer/src/huly/huly.ts#L582-L618","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the `class:` front-matter field of the reported docFile","Set it to the document class supported by Teamspaces (matching the exporter's exact identifier)","Move controlled-document files into the OrgSpace folder instead of the Teamspace","Re-export from Huly so document classes match the importer version"],"exampleFix":"// before (doc md front-matter)\nclass: documents.class.Page\n// after\nclass: documents.class.Document","handlingStrategy":"validation","validationCode":"for (const f of fs.readdirSync(teamspaceDir).filter(f => f.endsWith('.md'))) {\n  const h = readYamlHeader(path.join(teamspaceDir, f))\n  if (h?.class !== undefined && h.class !== expectedTeamspaceDocClass) {\n    throw new Error(`${f}: unexpected class ${h.class} in teamspace`)\n  }\n}","typeGuard":"function isTeamspaceDoc(h: unknown): boolean {\n  return typeof h === 'object' && h !== null && (h as any).class === 'documents.class.Document'\n}","tryCatchPattern":"try {\n  await importer.workspaceData(folder)\n} catch (e) {\n  if (e instanceof Error && e.message.includes('Unknown document class')) {\n    console.error('Fix the `class:` front-matter of the reported file:', e.message)\n  } else throw e\n}","preventionTips":["Only place teamspace-supported document markdown inside Teamspace folders","Never hand-edit class identifiers in front-matter","Keep controlled documents in OrgSpace folders, not Teamspaces","Match exporter/importer versions so class ids are identical"],"tags":["importer","front-matter","unsupported-value"],"backgroundTag":"unknown-entity-class","analyzedSha":"63e28dc96483967b2fc21c881b3f1023c1de7718","analyzedAt":"2026-08-29T15:21:27.377Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}