OpenBB-finance/OpenBB · error · OpenBBError

Invalid 'filters_dict' format. Must be a dictionary or seria

Error message

Invalid 'filters_dict' format. Must be a dictionary or serialized JSON string.

What it means

Raised when filters_dict is neither None, a dict, nor a JSON string that decodes to a dict (e.g. the string parsed fine but produced a list or scalar). The provider requires a mapping of screener filter keys to allowed values.

Source

Thrown at openbb_platform/providers/finviz/openbb_finviz/models/equity_screener.py:168

            raise OpenBBError(
                f"Invalid preset '{v}'. Please rename the file to use as a preset."
            )
        return v if v else None

    @field_validator("filters_dict", mode="before", check_fields=False)
    @classmethod
    def validate_filters_dict(cls, v):
        """Validate the filters_dict."""
        if isinstance(v, str):
            # pylint: disable=import-outside-toplevel
            import json

            try:
                v = json.loads(v)
            except json.JSONDecodeError as e:
                raise OpenBBError(f"Invalid JSON format for 'filters_dict': {e}") from e
        if v is not None and not isinstance(v, dict):
            raise OpenBBError(
                "Invalid 'filters_dict' format. Must be a dictionary or serialized JSON string."
            )

        return v


class FinvizEquityScreenerData(EquityScreenerData):
    """Finviz Equity Screener Data. Actual returned data varies by the 'metric' parameter."""

    __alias_dict__ = {
        "symbol": "Ticker",
        "name": "Company",
        "earnings_date": "Earnings",
        "sector": "Sector",
        "industry": "Industry",
        "country": "Country",
        "shares_outstanding": "Outstanding",
        "shares_float": "Float",

View on GitHub (pinned to 3e071fcc2c)

Solutions

Supply a plain dict mapping Finviz filter names to values
If converting from another structure, build the dict explicitly before passing
Add an isinstance(x, dict) assert in calling code during development

Example fix

# before
q = FinvizEquityScreenerQueryParams(filters_dict=[("Debt/Equity", "Over 0.5")])

# after
q = FinvizEquityScreenerQueryParams(filters_dict={"Debt/Equity": "Over 0.5"})

Defensive patterns

Strategy: type-guard

Validate before calling

assert filters_dict is None or isinstance(filters_dict, dict), (
    "filters_dict must be a dict (or JSON string decoding to a dict)"
)

Type guard

def is_filters_dict(v) -> bool:
    if v is None:
        return True
    if isinstance(v, dict):
        return True
    if isinstance(v, str):
        try:
            return isinstance(json.loads(v), dict)
        except json.JSONDecodeError:
            return False
    return False

Prevention

Convert tabular/paired data to a dict explicitly before passing
Assert the type at the call site during development

When it happens

Trigger: Passing filters_dict as a list of tuples; passing '[1,2,3]' (valid JSON but not an object); passing a set or a pandas Series.

Common situations: Programmatically deriving filters from tabular data (rows/Series) instead of a mapping; over-general serialization code that emits arrays.

Related errors

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