{"record":{"id":"9a84837d37d0c20b","repo":"hcengineering/platform","slug":"unknown-issue-class-issueheader-class-in-issu","errorCode":null,"errorMessage":"Unknown issue class ${issueHeader.class} in ${issueFile}","messagePattern":"Unknown issue class (.+?) in (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/importer/src/huly/huly.ts","lineNumber":511,"sourceCode":"          assignee: this.findPersonByName(issueHeader.assignee),\n          // Gantt scheduling fields\n          startDate: parseIsoDate(issueHeader.startDate),\n          dueDate: parseIsoDate(issueHeader.dueDate),\n          deadline: parseIsoDate(issueHeader.deadline),\n          componentLabel: issueHeader.component,\n          milestoneLabel: issueHeader.milestone,\n          predecessors: issueHeader.predecessors\n        }\n\n        builder.addIssue(projectPath, issuePath, issue, parentIssuePath)\n\n        // Process sub-issues if they exist\n        const subDir = path.join(currentPath, issueFile.replace('.md', ''))\n        if (fs.existsSync(subDir) && fs.statSync(subDir).isDirectory()) {\n          await this.processIssuesRecursively(builder, projectIdentifier, projectPath, subDir, issuePath)\n        }\n      } else {\n        throw new Error(`Unknown issue class ${issueHeader.class} in ${issueFile}`)\n      }\n    }\n  }\n\n  private findPersonByName (name?: string): Ref<Person> | undefined {\n    if (name === undefined) {\n      return undefined\n    }\n\n    const person = this.personsByName.get(name)\n    if (person === undefined) {\n      throw new Error(`Person not found: ${name}`)\n    }\n    return person\n  }\n\n  private async getPersonIdByEmail (email: string): Promise<PersonId> {\n    const personId = this.personIdByEmail.get(email)","sourceCodeStart":493,"sourceCodeEnd":529,"githubUrl":"https://github.com/hcengineering/platform/blob/63e28dc96483967b2fc21c881b3f1023c1de7718/packages/importer/src/huly/huly.ts#L493-L529","documentation":"While walking an imported project folder, processIssuesRecursively reads each .md file's YAML front-matter and dispatches on `class`. Files with no class are skipped, but a file that declares a class other than tracker.class.Issue cannot be imported as an issue, so the importer throws. This indicates a malformed or non-issue markdown file inside a project directory.","triggerScenarios":"processImportFolder → processIssuesRecursively encounters an issue .md file whose front-matter `class:` is set to something other than tracker.class.Issue (or a stale/foreign class id from a different export version).","commonSituations":"Hand-crafted issue files with a typo in the class; copying markdown files from another Huly area (e.g. documents) into a project folder; a version mismatch where the tracker Issue class identifier changed between export and import.","solutions":["Check the `class:` field in the front-matter of the reported issueFile","Set it to tracker.class.Issue (the exact identifier used by the matching Huly version)","Move non-issue markdown files (documents, notes) out of the project's issue directory","Re-export from the source Huly workspace to regenerate correctly-classed issue files"],"exampleFix":"// before (123..md front-matter)\nclass: tracker.class.Task\n// after\nclass: tracker.class.Issue","handlingStrategy":"validation","validationCode":"const files = fs.readdirSync(projectDir).filter(f => f.endsWith('.md'))\nfor (const f of files) {\n  const header = readYamlHeader(path.join(projectDir, f))\n  if (header?.class !== undefined && header.class !== 'tracker.class.Issue') {\n    throw new Error(`${f}: expected tracker.class.Issue, got ${header.class}`)\n  }\n}","typeGuard":"function isIssueHeader(h: unknown): h is HulyIssueHeader & { class: 'tracker.class.Issue' } {\n  return typeof h === 'object' && h !== null && (h as any).class === 'tracker.class.Issue'\n}","tryCatchPattern":"try {\n  await importer.workspaceData(folder)\n} catch (e) {\n  if (e instanceof Error && e.message.includes('Unknown issue class')) {\n    console.error('Non-issue markdown inside project folder:', e.message)\n  } else throw e\n}","preventionTips":["Only place tracker.class.Issue markdown files inside project issue directories","Keep documents/notes in their own folders, never mixed with issues","Copy front-matter class identifiers verbatim from exporter output","Pin importer and exporter to matching versions"],"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"}