OpenBB-finance/OpenBB · error · ValueError

Hierarchy '{table_id}' not found. Available: {[h['id'] for h

Error message

Hierarchy '{table_id}' not found. Available: {[h['id'] for h in available_hierarchies]}

What it means

Raised when an explicit table_id was passed to get_dataflow_hierarchy_table but none of the available hierarchy entries matches it by id. The message enumerates the valid ids, which may include 'split table' ids of the form 'base_id:top_level_code_id' — a common source of mismatch.

Source

Thrown at openbb_platform/providers/imf/openbb_imf/utils/metadata.py:1471

        if not available_hierarchies:
            raise ValueError(
                f"No presentation hierarchies found for dataflow '{dataflow_id}'"
            )

        # Track if this is a split table (one top-level code from a multi-code hierarchy)
        top_level_code_filter: str | None = None
        base_hierarchy_id: str | None = None

        if table_id:
            # Find the specific table
            selected_table = None
            for h in available_hierarchies:
                if h["id"] == table_id:
                    selected_table = h
                    break
            if not selected_table:
                raise ValueError(
                    f"Hierarchy '{table_id}' not found. "
                    f"Available: {[h['id'] for h in available_hierarchies]}"
                )
            # Check if this is a split table (format: "base_id:top_level_code_id")
            if ":" in table_id:
                base_hierarchy_id, top_level_code_filter = table_id.split(":", 1)
            else:
                base_hierarchy_id = table_id
        else:
            selected_table = available_hierarchies[0]
            table_id = selected_table.get("id", "")
            if table_id and ":" in table_id:
                base_hierarchy_id, top_level_code_filter = table_id.split(":", 1)
            else:
                base_hierarchy_id = table_id

        # Handle hierarchy-based presentations
        # Use base_hierarchy_id to look up the actual hierarchy object

View on GitHub (pinned to 3e071fcc2c)

Solutions

Read the 'Available:' list in the message and use one of those exact ids, including any ':code' suffix.
If you only know the base hierarchy id, call get_dataflow_hierarchies and search entries whose id starts with 'base_id:'.
Do not persist table ids long-term; re-resolve them each run from get_dataflow_hierarchies.

Example fix

# before
table = meta.get_dataflow_hierarchy_table('FSIBSIS', table_id='HIER_X')

# after
avail = {h['id'] for h in meta.get_dataflow_hierarchies('FSIBSIS')}
table_id = next((t for t in avail if t.split(':')[0] == 'HIER_X'), None)
table = meta.get_dataflow_hierarchy_table('FSIBSIS', table_id=table_id)

Defensive patterns

Strategy: validation

Validate before calling

available = {h['id'] for h in meta.get_dataflow_hierarchies(df_id)}
if table_id is not None and table_id not in available:
    candidates = [t for t in available if t.split(':')[0] == table_id.split(':')[0]]
    table_id = candidates[0] if candidates else None

Try / catch

try:
    meta.get_dataflow_hierarchy_table(df_id, table_id)
except ValueError as e:
    if 'Available:' in str(e):
        # parse the printed list and re-select a valid id programmatically
        valid = eval(str(e).split('Available:')[1].strip())
        table_id = valid[0]
    else:
        raise

Prevention

Always source table ids from get_dataflow_hierarchies in the same session.
Remember split ids contain ':' — match on the prefix if unsure.

When it happens

Trigger: Passing a bare hierarchy id when the available entries are split ids like 'HIER1:CODE_A' (or vice versa); passing an id obtained from a different/older catalog snapshot; case mismatches.

Common situations: Persisting table ids from an earlier session and reusing them after the IMF reorganized hierarchies; UI dropdowns populated from stale metadata; hand-typing ids from documentation.

Related errors

AI-assisted analysis of OpenBB-finance/OpenBB@3e071fcc2c (2026-08-14). Data as JSON: /api/errors/1c2bfd875c893913. Report an issue: GitHub.