OpenBB-finance/OpenBB · error · OpenBBError

Invalid value '{item}' for '{field}' (provider: '{provider}'

Error message

Invalid value '{item}' for '{field}' (provider: '{provider}'). Must be one of: {choices}

What it means

OpenBBError raised by the extra-params filter (openbb_core/app/static/utils/filters.py) when a provider-specific parameter value is not in the provider's declared 'choices' list for that field. The filter splits comma-separated strings into items and validates each against provider_properties['choices'] before forwarding kwargs to the provider.

Source

Thrown at openbb_platform/core/openbb_core/app/static/utils/filters.py:66

                        check_single_item(
                            new,
                            f"{field} -> multiple items not allowed for '{provider}'",
                        )

                    choices = (
                        provider_properties.get("choices")
                        if isinstance(provider_properties, dict)
                        else None
                    )
                    if choices:
                        items = (
                            [s.strip() for s in new.split(",")]
                            if isinstance(new, str) and "," in new
                            else [new]
                        )
                        for item in items:
                            if item not in choices:
                                raise OpenBBError(
                                    f"Invalid value '{item}' for '{field}'"
                                    f" (provider: '{provider}')."
                                    f" Must be one of: {choices}"
                                )

                    kwargs[p][field] = new
                    break
    else:
        provider = kwargs.get("provider_choices", {}).get("provider")
        for param_category in ("standard_params", "extra_params"):
            if param_category in kwargs:
                for field, value in kwargs[param_category].items():
                    if isinstance(value, list):
                        kwargs[param_category][field] = ",".join(map(str, value))
                    check_single_item(
                        kwargs[param_category][field],
                        f"{field} -> multiple items not allowed for '{provider}'",
                    )

View on GitHub (pinned to 3e071fcc2c)

Solutions

Use one of the values listed in the error's 'Must be one of: (...)' message
Inspect allowed choices before calling: obb.coverage.command.get('...') or the command's /schema endpoint / help signature
Update the provider package if docs say new choices were added (pip install -U openbb-fmp)

Example fix

# before
res = obb.equity.fundamental.income('AAPL', provider='fmp', period='yearly')

# after
res = obb.equity.fundamental.income('AAPL', provider='fmp', period='annual')

Defensive patterns

Strategy: validation

Validate before calling

from openbb import obb

def get_choices(command_path: str, param: str) -> tuple | None:
    # obb.coverance/command schema exposes provider parameter details
    cmd = obb.coverage
    return None  # inspect /schema endpoint or command docstring for choices

Type guard

def valid_choice(value: str, choices: tuple) -> bool:
    return value in choices

Try / catch

from openbb_core.app.model.abstract.error import OpenBBError

try:
    res = obb.equity.fundamental.income('AAPL', provider='fmp', period=p)
except OpenBBError as e:
    if 'Must be one of' in str(e):
        p = 'annual'  # fallback to a known-valid choice
        res = obb.equity.fundamental.income('AAPL', provider='fmp', period=p)
    else:
        raise

Prevention

Read the command's parameter schema (docs or /schema endpoint) for allowed choices
Never reuse one provider's enum vocabulary with another provider
Centralize provider-specific defaults in config instead of scattering literals

When it happens

Trigger: Passing a provider-specific argument with an invalid enum value, e.g. obb.equity.fundamental.income(symbol='AAPL', provider='fmp', period='yearly') where the provider only accepts choices like ('annual','quarter'); comma-lists where any single item is not in choices also fail.

Common situations: Using another provider's vocabulary for a shared concept (yearly vs annual vs FY); guessing parameter values instead of checking the command signature; provider package update that renamed allowed choices; copy-pasting example code written for a different provider.

Related errors

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