What causes "Failed to download {category} -> {e}" in OpenBB-finance/OpenBB?

Inspect the chained exception (`raise ... from e` preserves it) to identify the true cause

OpenBB-finance/OpenBB · error · OpenBBError

Failed to download {category} -> {e}

Error message

Failed to download {category} -> {e}

What it means

Raised by the BLS update_survey_files maintenance helper when download_category_series_ids throws for the given category; the original exception is chained (`from e`). The message wraps the underlying failure - which can be a network error, a parsing error on the BLS FTP/HTTP asset, or the EmptyDataError from a bad category map lookup. The root cause is in the chained exception.

Source

Thrown at openbb_platform/providers/bls/openbb_bls/utils/helpers.py:419

    """
    # pylint: disable=import-outside-toplevel
    import json  # noqa
    from importlib.resources import files
    from pathlib import Path
    from openbb_core.app.model.abstract.error import OpenBBError
    from openbb_bls.utils.constants import SURVEY_CATEGORY_NAMES
    from numpy import nan
    from pandas import DataFrame

    if category not in SURVEY_CATEGORY_NAMES:
        raise OpenBBError(
            f"Category '{category}' not found. Choose from {list(SURVEY_CATEGORY_NAMES)}"
        )

    try:
        ids, codes = await download_category_series_ids(category)
    except Exception as e:  # pylint: disable=broad-except
        raise OpenBBError(f"Failed to download {category} -> {e}") from e

    assets_path = Path(str(files("openbb_bls").joinpath("assets")))

    # Save the code map to a JSON file.
    if codes:
        with open(assets_path.joinpath(f"{category}_codes.json"), "w") as f:
            json.dump(codes, f, indent=4)

    # Save the series IDs to a CSV file.
    if ids:
        df = DataFrame(ids)
        df = df.replace({nan: None, "nan": None, "''": None}).dropna(how="all", axis=1)
        df.to_csv(
            assets_path.joinpath(f"{category}_series.xz"), index=False, compression="xz"
        )

View on GitHub (pinned to 3e071fcc2c)

Solutions

Inspect the chained exception (`raise ... from e` preserves it) to identify the true cause
Verify network access to the BLS download endpoints and retry after transient failures
If parsing failed, check whether BLS changed the asset format and adjust get_survey_asset
Confirm the category passes SURVEY_CATEGORY_NAMES and SURVEY_CATEGORY_MAP checks first

Example fix

# before
await update_survey_files('employment')  # opaque wrapper error

# after
try:
    await update_survey_files('employment')
except OpenBBError as e:
    print('root cause:', e.__cause__)  # inspect chained exception

Defensive patterns

Strategy: retry

Validate before calling

import socket
socket.setdefaulttimeout(30)  # BLS asset downloads can hang/slow

Try / catch

try:
    await update_survey_files(cat)
except OpenBBError as e:
    cause = e.__cause__  # real failure: network, parse, or category guard
    if is_transient(cause):
        await asyncio.sleep(10); await update_survey_files(cat)

Prevention

Always inspect __cause__ - the wrapper hides the real error
Run asset regeneration on a machine with reliable access to bls.gov
Validate the category against both constants before starting a long run

When it happens

Trigger: BLS survey download endpoints unreachable (offline, firewall, DNS), a survey asset whose layout changed so parsing fails, or the nested EmptyDataError from an unsupported category inside the map.

Common situations: Running asset regeneration on CI without network access; BLS changing their FTP file format; transient outages of bls.gov during bulk regeneration runs.

Related errors

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