hcengineering/platform · error

Unknown space class ${spaceConfig.class} in ${spaceName}

Error message

Unknown space class ${spaceConfig.class} in ${spaceName}

What it means

During Huly workspace import, processImportFolder reads each top-level .yaml file as a space configuration and dispatches on its `class` field. Only a fixed set of classes is supported: tracker Project, document Teamspace, documents OrgSpace, plus Enum/Association/MasterTag (which are skipped for later processing). If the YAML declares any other class value, the importer cannot map it to a known space type and throws this error.

Source

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

          case documents.class.OrgSpace: {
            const orgSpace = await this.processOrgSpace(spaceConfig as HulyOrgSpaceSettings)
            builder.addOrgSpace(spacePath, orgSpace)
            if (fs.existsSync(spacePath) && fs.statSync(spacePath).isDirectory()) {
              await this.processControlledDocumentsRecursively(builder, spacePath, spacePath)
            }
            break
          }

          case core.class.Enum:
          case core.class.Association:
          case card.class.MasterTag: {
            this.logger.log(`Skipping ${spaceName}: will be processed later`)
            break
          }

          default: {
            throw new Error(`Unknown space class ${spaceConfig.class} in ${spaceName}`)
          }
        }
      } catch (error) {
        const message = error instanceof Error ? error.message : String(error)
        throw new Error(`Invalid space configuration in ${spaceName}: ${message}`)
      }
    }

    const { docs, mixins, updates, files } = await this.cardsProcessor.processDirectory(folderPath)

    const ws = builder.build()
    ws.unifiedDocs = {
      docs: Array.from(docs.values()).flat(),
      mixins: Array.from(mixins.values()).flat(),
      updates: Array.from(updates.values()).flat(),
      files: Array.from(files.values())
    }
    return ws

View on GitHub (pinned to 63e28dc964)

Solutions

1. Open the offending <spaceName>.yaml in the import folder and check the `class:` field
2. Set `class` to one of the supported values (Project, Teamspace, OrgSpace) or correct the identifier to match the Huly class from the same version that produced the export
3. Re-export from Huly with a matching importer version so class identifiers align
4. If the file is not actually a space config, remove the `class` field entirely (the importer will skip it with a log message instead of throwing)
5. Delete the stale/irrelevant YAML file from the import folder

Example fix

// before (spaceName.yaml)
class: tracker.class.Projet
title: My Project
// after
class: tracker.class.Project
title: My Project

const SUPPORTED = ['tracker.class.Project','document.class.Teamspace','documents.class.OrgSpace','core.class.Enum','core.class.Association','card.class.MasterTag']
for (const f of fs.readdirSync(folder).filter(f => f.endsWith('.yaml') && f !== 'settings.yaml')) {
  const cfg = yaml.load(fs.readFileSync(path.join(folder, f), 'utf8'))
  if (cfg?.class !== undefined && !SUPPORTED.includes(cfg.class)) {
    console.error(`${f}: unsupported class ${cfg.class}`)
    process.exitCode = 1
  }
}

function isKnownSpaceClass(c: unknown): c is HulySpaceSettings['class'] {
  return typeof c === 'string' && ['tracker.class.Project','document.class.Teamspace','documents.class.OrgSpace','core.class.Enum','core.class.Association','card.class.MasterTag'].includes(c)
}

try {
  await importer.workspaceData(folder)
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Invalid space configuration')) {
    console.error('Bad space config:', e.message)
  } else throw e
}

When it happens

Trigger: Calling workspaceData/import on a Huly export folder where a *.yaml space config file has a `class:` value that is not tracker.class.Project, document.class.Teamspace, documents.class.OrgSpace, core.class.Enum, core.class.Association, or card.class.MasterTag — e.g. a typo, an older/newer export format, or a hand-edited class name.

Common situations: Hand-editing space YAML files and mistyping the class; importing a Huly export produced by a different version whose class identifiers changed; copying a YAML from another tool that uses different class names; leaving a leftover or experimental config file in the folder.

Related errors

• Invalid space configuration in ${spaceName}: ${message}
• Unknown issue class ${issueHeader.class} in ${issueFile}
• Unknown document class ${docHeader.class} in ${docFile}
• Unsupported card type: ${cardType} in ${cardPath}
• Invalid master tag data

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