What causes "Invalid master tag data" in hcengineering/platform?

Set the file's YAML `class:` header to exactly the card.class.MasterTag value expected by the importer version.

Invalid master tag data

Error message

Invalid master tag data

What it means

Thrown by CardsProcessor.createMasterTag after schema validation passes but the parsed document's `class` field does not equal card.class.MasterTag. It is an internal consistency check ensuring only master-tag documents reach master tag creation; a mismatch means the file declared a different class in its YAML header.

Source

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

        childCardPath,
        cardProps,
        masterTagId,
        masterTagAssociaions,
        masterTagAttributes,
        parentCardId
      )
    }
  }

  private async createMasterTag (
    data: Record<string, any>,
    filePath: string,
    parentMasterTagId?: Ref<MasterTag>
  ): Promise<UnifiedDoc<MasterTag>> {
    this.validateFormat(data, MasterTagSchema, filePath)
    const { class: _class, title } = data
    if (_class !== card.class.MasterTag) {
      throw new Error('Invalid master tag data')
    }

    return {
      _class: card.class.MasterTag,
      props: {
        _id: this.metadataRegistry.getRef(filePath) as Ref<MasterTag>,
        space: core.space.Model,
        extends: parentMasterTagId ?? card.class.Card,
        label: ('embedded:embedded:' + title) as IntlString,
        kind: 0,
        icon: card.icon.MasterTag
      }
    }
  }

  private async processTag (
    tagPath: string,
    tagConfig: Record<string, any>,

View on GitHub (pinned to 63e28dc964)

Solutions

Set the file's YAML `class:` header to exactly the card.class.MasterTag value expected by the importer version.
Route the document to the correct factory (createTag/createCard) based on its `class` instead of calling createMasterTag.
Verify no typo/case mismatch in the class string (e.g. `card:class:mastertag` vs `card:class:MasterTag`).

Example fix

// before (YAML header)
class: card:class:Tag
title: Priority
// after
class: card:class:MasterTag
title: Priority

Defensive patterns

Strategy: type-guard

Validate before calling

function assertMasterTagFile(header: { class?: string }): boolean {
  return header.class === 'card:class:MasterTag' // match card.class.MasterTag for your version
}

Type guard

function isMasterTagData(d: { class?: string; title?: string }): d is { class: typeof card.class.MasterTag; title: string } {
  return d.class === card.class.MasterTag && typeof d.title === 'string'
}

Try / catch

try {
  await processor.masterTag(file)
} catch (e) {
  if (e instanceof Error && e.message === 'Invalid master tag data') {
    console.error(`${file}: class header is not card.class.MasterTag — route to the correct factory or fix the header`)
  } else throw e
}

Prevention

Dispatch documents to factories by their parsed `class` value, not by filename or directory.
Reference card.class.MasterTag constant instead of hardcoding the string.
Keep one canonical master-tag template in the repo.

When it happens

Trigger: Calling masterTag (or a flow that routes to createMasterTag) with data parsed from a file whose YAML header `class:` is not card.class.MasterTag — e.g. a Tag or plain Card document passed to the wrong factory.

Common situations: Routing a mixed directory of tags and master tags through the masterTag entry point; copy-pasted headers where `class:` was left as `card:class:Tag`; dispatch code that maps files to creators by extension rather than class.

Related errors

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