hcengineering/platform · error · Error

interface not found: ${_interface}

Error message

interface not found: ${_interface}

What it means

Hierarchy.getInterface resolves an interface Ref from the classifiers map and additionally verifies the resolved classifier is actually an Interface. It throws if the ref is unregistered OR resolves to a Class instead of an Interface. This guards against passing a class ref where an interface ref is expected.

Source

Thrown at foundations/core/packages/core/src/hierarchy.ts:228

  hasClass<T extends Obj = Obj>(_class: Ref<Class<T>>): boolean {
    const data = this.classifiers.get(_class)

    return !(data === undefined || this.isInterface(data))
  }

  getClassOrInterface (_class: Ref<Class<Obj>>): Class<Obj> {
    const data = this.classifiers.get(_class)
    if (data === undefined) {
      throw new Error('class not found: ' + _class)
    }
    return data
  }

  getInterface (_interface: Ref<Interface<Doc>>): Interface<Doc> {
    const data = this.classifiers.get(_interface)
    if (data === undefined || !this.isInterface(data)) {
      throw new Error('interface not found: ' + _interface)
    }
    return data
  }

  getDomain (_class: Ref<Class<Obj>>): Domain {
    const domain = this.findDomain(_class)
    if (domain === undefined) {
      throw new Error(`domain not found: ${_class} `)
    }
    return domain
  }

  public findDomain (_class: Ref<Class<Doc>>): Domain | undefined {
    const klazz = this.findClass(_class)
    if (klazz === undefined) return
    if (klazz.domain !== undefined) {
      return klazz.domain
    }

View on GitHub (pinned to 63e28dc964)

Solutions

1. Verify you are using the interface Ref (core.interface.X / plugin.interface.X), not the class Ref
2. Ensure the Interface classifier tx was applied to the hierarchy before the call
3. Check the plugin defining the interface is installed and its model loaded
4. Use findAttribute/isInterface checks beforehand if the interface may legitimately be missing

Example fix

// before
const iface = hierarchy.getInterface(someRef) // someRef is a class ref
// after
const iface = hierarchy.getInterface(core.interface.ClassDoc) // correct interface ref

if (hierarchy.findClass(_interface) === undefined || !hierarchy.isInterface(hierarchy.getClass(_interface))) {
  throw new Error(`${String(_interface)} is not a registered interface`)
}
const iface = hierarchy.getInterface(_interface)

function isRegisteredInterface(h: Hierarchy, r: Ref<Interface<Doc>>): boolean {
  const c = h.findClass(r)
  return c !== undefined && h.isInterface(c)
}

let iface: Interface<Doc>
try {
  iface = hierarchy.getInterface(ref)
} catch (err) {
  console.warn(`Interface ${String(ref)} not registered or is a class`)
  throw err
}

When it happens

Trigger: Calling getInterface (e.g. from withStateInterface) with a ref not present in classifiers, or with a Ref<Class> mistakenly used as an interface, or before the interface's model tx has been added to the hierarchy.

Common situations: Confusing core.class.X with core.interface.X (they are sibling refs); interfaces defined in a plugin that is not loaded; applying interface txes out of order so withStateInterface runs before registration.

Related errors

• domain not found: ${_class}
• descendants not found: ${_class}
• ancestors not found: ${_class}
• class not found: ${_class}
• attribute not found: ${name}

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