hcengineering/platform · error

Hierarchy is not defined

Error message

Hierarchy is not defined

What it means

Plain Error thrown by MediaClient.getHierarchy when the internal hierarchy field is still undefined. getHierarchy is a non-nullable accessor — the client expects connect() (or the initialization path assigning this.hierarchy) to have run first.

Source

Thrown at pods/media/src/client.ts:204

  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. Call connect()/initialize and await it before any getHierarchy()/getModel() call
2. Guard call sites with a connection-state check or expose an isConnected() helper
3. Lazily initialize the hierarchy inside getHierarchy() if the API permits
4. Restructure so accessors are only handed out after the client reports ready
5. Add an assertion/test covering the initialization order

Example fix

// before
const client = new MediaClient(url)
const hierarchy = client.getHierarchy() // throws
// after
const client = new MediaClient(url)
await client.connect()
const hierarchy = client.getHierarchy()

if (!client.isConnected?.()) await client.connect()

try {
  const hierarchy = client.getHierarchy()
} catch {
  await client.connect()
  const hierarchy = client.getHierarchy()
}

When it happens

Trigger: Calling client.getHierarchy() before client.connect()/init() completed, after a failed connection attempt that left hierarchy unassigned, or after close() on a client whose implementation clears state.

Common situations: Constructing MediaClient in one place and calling accessors in another without awaiting connect; race conditions where a consumer fires before initialization completes; tests instantiating the client without a server; forgetting to await an async init.

Related errors

• Hierarchy is not defined
• Model 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/48de4f54e75f7812. Report an issue: GitHub.