OpenBB-finance/OpenBB · error · ValueError

Hierarchy '{base_hierarchy_id or table_id}' not found in cac

Error message

Hierarchy '{base_hierarchy_id or table_id}' not found in cache

What it means

Internal consistency error: the selected table id resolved, but the underlying hierarchy object is missing from self.hierarchies (keyed by base_hierarchy_id, i.e. the part before ':'). It means the available-hierarchies list and the raw hierarchy cache are out of sync — typically a partially loaded or stale hierarchy.json.

Source

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

                )
            # 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
        hierarchy = self.hierarchies.get(base_hierarchy_id or table_id)
        if not hierarchy:
            raise ValueError(
                f"Hierarchy '{base_hierarchy_id or table_id}' not found in cache"
            )

        if not table_id:
            raise ValueError("table_id cannot be None")

        codelist_id = self._hierarchy_to_codelist_map.get(base_hierarchy_id or table_id)

        dataflow_obj = self.dataflows.get(dataflow_id, {})
        agency_id = dataflow_obj.get("agencyID", "IMF")
        agency_clean = agency_id.replace(".", "_")

        structure_ref = dataflow_obj.get("structureRef", {})
        dsd_id = structure_ref.get("id")
        dsd_obj = self.datastructures.get(dsd_id, {}) if dsd_id else {}
        dimensions = dsd_obj.get("dimensions", []) if isinstance(dsd_obj, dict) else []

        indicator_dimension_order: dict[str, int] = {}

View on GitHub (pinned to 3e071fcc2c)

Solutions

Clear and re-download the IMF hierarchy metadata caches so self.hierarchies and the availability list are rebuilt together.
If it persists, the upstream mapping is inconsistent — catch the ValueError and fall back to the flat indicator list.
Report the specific hierarchy id to the provider maintainers if reproducible after a cache refresh.

Example fix

# before
table = meta.get_dataflow_hierarchy_table(df_id, table_id)

# after
try:
    table = meta.get_dataflow_hierarchy_table(df_id, table_id)
except ValueError as e:
    if 'not found in cache' in str(e):
        meta.hierarchies.clear()  # force re-fetch on next init
        meta = IMFSDMXMetadata(...)  # reload
        table = meta.get_dataflow_hierarchy_table(df_id, table_id)
    else:
        raise

Defensive patterns

Strategy: fallback

Validate before calling

base = (table_id or '').split(':')[0]
hierarchy_cached = base in meta.hierarchies
if not hierarchy_cached:
    meta = rebuild_metadata()  # refresh caches before calling

Try / catch

try:
    meta.get_dataflow_hierarchy_table(df_id, table_id)
except ValueError as e:
    if 'not found in cache' in str(e):
        # internal cache desync: rebuild once, then give up with flat fallback
        table = {'indicators': meta.get_indicators_in(df_id)}
    else:
        raise

Prevention

Invalidate all IMF metadata caches together (dataflows, datastructures, hierarchies).
Treat cache-desync errors as non-retryable until caches are refreshed.

When it happens

Trigger: available_hierarchies derived from one cache (e.g. DSD/codelist mapping) referencing a hierarchy id that was pruned or never loaded into self.hierarchies; concurrent cache population racing the read.

Common situations: Interrupted first-load of hierarchy metadata, mixed-version cached JSON files, new hierarchies advertised by the catalog before their definitions are downloadable.

Related errors

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