hcengineering/platform · error · Error

Hierarchy is not defined

Error message

Hierarchy is not defined

What it means

The REST client adapter lazily receives a Hierarchy (model metadata) after initialization; getHierarchy throws 'Hierarchy is not defined' when it is called before the adapter has been initialized/connected with the model. The hierarchy is required for object-class operations.

Source

Thrown at foundations/core/packages/api-client/src/rest/adapter.ts:85

  async findOne<T extends Doc>(
    _class: Ref<Class<T>>,
    query: DocumentQuery<T>,
    options?: FindOptions<T>
  ): Promise<WithLookup<T> | undefined> {
    return await this.client.findOne(_class, query, options)
  }

  async searchFulltext (query: SearchQuery, options: SearchOptions): Promise<SearchResult> {
    return await this.client.searchFulltext(query, options)
  }

  async close (): Promise<void> {
    // No ned to close the REST client
  }

  getHierarchy (): Hierarchy {
    if (this.hierarchy === undefined) {
      throw new Error('Hierarchy is not defined')
    }
    return this.hierarchy
  }

  getModel (): ModelDb {
    if (this.model === undefined) {
      throw new Error('Model is not defined')
    }
    return this.model
  }
}

View on GitHub (pinned to 63e28dc964)

Solutions

1. Ensure the adapter is fully initialized (await connect / the init that assigns hierarchy) before calling getHierarchy.
2. Use the high-level client factory (connect / getClient) instead of instantiating the REST adapter manually.
3. Await all setup promises before issuing the first model-dependent call.

Example fix

// before
const adapter = new RestClientAdapter(url, workspace, token)
const h = adapter.getHierarchy()
// after
const client = await connect(url, { workspace, token }) // performs full init
const h = client.getHierarchy()

// Only valid after awaiting the client factory
const client = await connect(url, { workspace, token }) // guarantees hierarchy assignment
if (client.getHierarchy == null) throw new Error('adapter does not expose a hierarchy')

function hasHierarchy(c: unknown): c is { getHierarchy: () => Hierarchy } {
  return typeof c === 'object' && c !== null && typeof (c as any).getHierarchy === 'function'
}

try {
  const hierarchy = adapter.getHierarchy()
} catch (e) {
  if (e instanceof Error && e.message === 'Hierarchy is not defined') {
    throw new Error('Adapter used before initialization — await connect()/init before model operations')
  }
  throw e
}

When it happens

Trigger: Calling client.getHierarchy() (or any API relying on it) on a RestClientAdapter before its hierarchy was assigned during init/connect; constructing the adapter manually and skipping the initialization step.

Common situations: Using the REST adapter directly instead of via the connect() factory, calling methods before an awaited init completes, race where an async setup assigns hierarchy after first use.

Related errors

• Model is not defined
• Hierarchy is not defined
• Model is not defined
• Message id is required
• Unknown content format

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