HKUDS/Vibe-Trading · error · ValueError

flows_columns must be an object mapping field to column name

Error message

flows_columns must be an object mapping field to column name

What it means

When loading flows from flows_path, an optional flows_columns mapping (field -> CSV column name) must be a dict/object if provided. Passing a list, string, or other type raises this error before file parsing begins.

Source

Thrown at agent/src/tools/cashflow_analytics_tool.py:360

    Returns:
        A ``CashFlowSeries``, or ``None`` when no flows were supplied.

    Raises:
        ValueError: If both sources were given, an inline record is malformed,
            or a currency is missing. File problems surface as
            ``CashFlowIngestError``, which is a ``ValueError``.
    """
    inline = kwargs.get("flows")
    path = kwargs.get("flows_path")
    if inline and path:
        raise ValueError("pass either flows or flows_path, not both")
    currency = kwargs.get("currency")

    if path:
        columns = kwargs.get("flows_columns")
        if columns is not None and not isinstance(columns, dict):
            raise ValueError("flows_columns must be an object mapping field to column name")
        return load_cashflows(
            str(path),
            columns=columns,
            currency=currency,
            default_kind=kwargs.get("flows_default_kind"),
            date_format=kwargs.get("flows_date_format"),
            invert_sign=bool(kwargs.get("flows_invert_sign", False)),
        )

    if not inline:
        return None
    if not isinstance(inline, list):
        raise ValueError("flows must be an array of {date, amount, kind} objects")
    if len(inline) > _MAX_INLINE_FLOWS:
        raise ValueError(f"flows may contain at most {_MAX_INLINE_FLOWS} entries")

    records: list[CashFlow] = []
    for index, item in enumerate(inline):

View on GitHub (pinned to 80ffdda44c)

Solutions

1. Pass a dict like {"date": "Date", "amount": "Amount", "kind": "Type"} or omit flows_columns entirely to use defaults

Example fix

# before
flows_columns=["Date", "Amount", "Kind"]
# after
flows_columns={"date": "Date", "amount": "Amount", "kind": "Kind"}

cols = kwargs.get("flows_columns")
if cols is not None and not isinstance(cols, dict):
    raise TypeError("flows_columns must be a dict")

from typing import TypeGuard

def is_column_mapping(v: object) -> TypeGuard[dict[str, str]]:
    return isinstance(v, dict) and all(isinstance(k, str) and isinstance(x, str) for k, x in v.items())

When it happens

Trigger: execute(flows_path="cf.csv", flows_columns=["date","amount"]) or flows_columns="date_col" — anything not isinstance(columns, dict).

Common situations: Confusion between a column-name list and a field->column mapping; YAML/JSON config parsed into a list instead of an object; agent guessing the parameter shape.

Related errors

• flows must be an array of {date, amount, kind} objects
• flows[{index}] must be an object
• amount must be numeric, got {self.amount!r}
• metadata must be a mapping, got {type(self.metadata).__name_
• CashFlowSeries members must be CashFlow, got {type(item).__n

AI-assisted analysis of HKUDS/Vibe-Trading@80ffdda44c (2026-08-28). Data as JSON: /api/errors/04a64120385cdd93. Report an issue: GitHub.