HKUDS/Vibe-Trading · error · CashFlowIngestError

{path}: unknown column mapping {field_name!r}; mappable fiel

Error message

{path}: unknown column mapping {field_name!r}; mappable fields are: {known}

What it means

load_cashflows' columns= argument maps canonical field names to header names; only names present in DEFAULT_COLUMN_ALIASES are mappable. An unrecognized field name raises CashFlowIngestError listing the valid fields.

Source

Thrown at agent/src/entities/ingest.py:115

        columns: Explicit overrides, canonical field -> file column name.
        path: File path, used only for error messages.

    Returns:
        Mapping of canonical field name to the file's column name, containing
        only fields that were actually found.

    Raises:
        CashFlowIngestError: If an explicit override names a column that the
            file does not contain, or overrides an unknown field.
    """
    resolved: dict[str, str] = {}
    lookup = {_canonical(col): col for col in header}

    if columns:
        for field_name, source_name in columns.items():
            if field_name not in DEFAULT_COLUMN_ALIASES:
                known = ", ".join(sorted(DEFAULT_COLUMN_ALIASES))
                raise CashFlowIngestError(
                    f"{path}: unknown column mapping {field_name!r}; "
                    f"mappable fields are: {known}"
                )
            if source_name not in header:
                raise CashFlowIngestError(
                    f"{path}: mapped column {source_name!r} for field "
                    f"{field_name!r} is not in the file. Columns present: "
                    f"{', '.join(header)}"
                )
            resolved[field_name] = source_name

    for field_name, aliases in DEFAULT_COLUMN_ALIASES.items():
        if field_name in resolved:
            continue
        for alias in aliases:
            if alias in lookup:
                resolved[field_name] = lookup[alias]
                break

View on GitHub (pinned to 80ffdda44c)

Solutions

1. Use only canonical field names as keys, with the CSV header as the value: columns={'amount': 'Net Amount'}
2. If the field you want isn't mappable, map an existing canonical field to the header that carries that data
3. Check the error's listed 'mappable fields are:' set for the exact valid keys

Example fix

# before
load_cashflows('f.csv', columns={'amnt': 'Amount'})
# after
load_cashflows('f.csv', columns={'amount': 'Amount'})

from agent.src.entities.ingest import DEFAULT_COLUMN_ALIASES
assert set(columns) <= set(DEFAULT_COLUMN_ALIASES), f'bad keys: {set(columns) - set(DEFAULT_COLUMN_ALIASES)}'

try:
    load_cashflows(path, columns=columns)
except CashFlowIngestError as e:
    if 'unknown column mapping' in str(e):
        columns = {k: v for k, v in columns.items() if k in DEFAULT_COLUMN_ALIASES}

When it happens

Trigger: load_cashflows('flows.csv', columns={'amnt': 'Amount'}) — 'amnt' is not a canonical field; only names like date, kind, amount, currency (per DEFAULT_COLUMN_ALIASES) are accepted.

Common situations: Guessing field names instead of checking the schema; renaming source columns and passing the new name as the dict key instead of the value; version differences that added/renamed mappable fields.

Related errors

• {path}: mapped column {source_name!r} for field {field_name!
• {path} row {row_number}: amount is blank. A missing amount m
• {path} row {row_number}: unit is blank and no unit=... fallb
• {path}: layout={layout!r} needs at least one column besides
• {path} row {row_number}: {row_label_column!r} is blank

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