hcengineering/platform · error

Tag should be inside master tag folder: ${currentPath}

Error message

Tag should be inside master tag folder: ${currentPath}

What it means

In the huly card importer, `processMetadata` encounters a YAML config describing a `card.class.Tag` but no master tag folder context (`parentMasterTagId`) is established. Tags in Huly must live under a master tag (type) folder, so the importer refuses to create an orphan tag and throws with the offending path.

Source

Thrown at packages/importer/src/huly/cards.ts:153

      switch (yamlConfig?.class) {
        case card.class.MasterTag: {
          const masterTagId = this.metadataRegistry.getRef(yamlPath) as Ref<MasterTag>
          const masterTag = await this.createMasterTag(yamlConfig, yamlPath, parentMasterTagId)
          const masterTagAttributes = await this.createAttributes(yamlPath, yamlConfig, masterTagId)

          this.metadataRegistry.setAttributes(yamlPath, masterTagAttributes)
          result.docs.set(yamlPath, [masterTag, ...Array.from(masterTagAttributes.values())])
          types.push(masterTag)

          const masterTagDir = path.join(currentPath, path.basename(yamlPath, '.yaml'))
          if (fs.existsSync(masterTagDir) && fs.statSync(masterTagDir).isDirectory()) {
            await this.processMetadata(masterTagDir, result, [], masterTagId)
          }
          break
        }
        case card.class.Tag: {
          if (parentMasterTagId === undefined) {
            throw new Error('Tag should be inside master tag folder: ' + currentPath)
          }
          await this.processTag(yamlPath, yamlConfig, result, parentMasterTagId)
          break
        }
        case core.class.Association: {
          const association = await this.createAssociation(yamlPath, yamlConfig)
          result.docs.set(yamlPath, [association])
          break
        }
        case core.class.Enum: {
          const enumDoc = await this.createEnum(yamlPath, yamlConfig)
          this.metadataRegistry.setEnumValues(yamlPath, yamlConfig.values)
          result.docs.set(yamlPath, [enumDoc])
          break
        }
        default:
          this.logger.log('Skipping class: ' + yamlConfig?.class)
      }

View on GitHub (pinned to 63e28dc964)

Solutions

1. Move the tag YAML file into the master tag folder it belongs to (or restore the master tag definition file)
2. Ensure the master tag is defined and processed before/in the same run so parentMasterTagId is set
3. Check directory structure: tags must be nested under the master tag directory the importer expects
4. Verify the export tool produced the expected folder hierarchy (master tag folder containing its tags)

Example fix

// before
// tags/
//   urgent.yaml        <- tag with no master tag folder above
// after
// master-tags/
//   statuses.yaml      <- master tag (type) definition
//   tags/
//     urgent.yaml      <- tag inside master tag folder

// before processing, verify every tag yaml is nested under a master tag folder
for (const tagPath of tagFiles) {
  if (!tagPath.startsWith(masterTagDir)) {
    console.warn(`tag outside master tag folder: ${tagPath}`)
  }
}

try {
  await importer.processDirectory(root)
} catch (err) {
  const m = /Tag should be inside master tag folder: (.+)/.exec((err as Error).message)
  if (m) console.error(`move ${m[1]} under its master tag folder`)
  throw err
}

When it happens

Trigger: Processing a directory tree where a tag YAML file appears outside any master tag folder — the master tag definition is missing, not yet processed (ordering), or the tag file sits in a directory that is not under the master tag directory.

Common situations: Exporting/authoring card data where tag files were moved out of their type folder; the master tag YAML is absent or misnamed so `parentMasterTagId` never gets set; directory traversal order processes the tag before its master tag folder.

Related errors

• ancestors not found: ${_class}
• class not found: ${_class}
• interface not found: ${_interface}
• domain not found: ${_class}
• descendants not found: ${_class}

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