HKUDS/Vibe-Trading · error · CashFlowIngestError

: mapped column for field is not in the file. Columns…

Error message

{path}: mapped column {source_name!r} for field {field_name!r} is not in the file. Columns present: {', '.join(header)}

What it means

Raised by _resolve_columns during cash-flow CSV ingestion when the user-supplied columns mapping names a source column that does not exist in the file's header row. The file was read successfully, but the explicit mapping points at a column name that is absent, so the field cannot be resolved. The message lists all columns actually present to help correct the mapping.

Solutions

Compare the mapping value against the 'Columns present' list in the message and fix the typo/whitespace exactly
Open the file and check for a BOM or padded header names; re-export or strip them
If the column genuinely has a different name, update the columns dict to that exact name
If the wrong delimiter split the header, pass delimiter=';' or delimiter='\t' explicitly

Example fix

# before
load_cashflows(p, columns={'date': 'TradeDate'})
# after
load_cashflows(p, columns={'date': ' TradeDate '.strip()})  # match exact header text

Defensive patterns

Strategy: validation

Validate before calling

import csv
from pathlib import Path

def check_mapping(path, columns, delimiter=None):
    with open(path, newline='', encoding='utf-8-sig') as f:
        header = next(csv.reader(f, delimiter=delimiter or ','))
    bad = {field: src for field, src in columns.items() if src not in header}
    if bad:
        raise ValueError(f'mapping targets not in header: {bad}; header={header}')

Type guard

def mapping_is_valid(header: list[str], columns: dict[str, str]) -> bool:
    return all(src in header for src in columns.values())

Try / catch

try:
    load_cashflows(p, columns=cols)
except CashFlowIngestError as e:
    if 'not in the file' in str(e):
        header = read_header(p)
        cols = {f: match(h, header) for f, h in cols.items()}  # repair and retry once

Prevention

Read the header first and assert your mapping values exist before loading
Normalize header cells (strip, remove BOM) before comparing
Keep per-source column maps in config tested against fixture files

When it happens

Trigger: Calling load_cashflows(path, columns={'date': 'TradeDate'}) (or load_panel with a columns mapping) where the header contains e.g. Date, Amount but not TradeDate. Any mapping value not found verbatim in the header triggers it.

Common situations: Typos in the mapping dict; column names with stray whitespace or a BOM prefix (Date); case differences; mapping copied from a different export template; delimiter misdetected so multiple header cells merge into one name.

Related errors

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

Appendix: source

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

        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

    return resolved


def _to_plain_number(text: str, decimal_separator: str | None) -> str:

View on GitHub (pinned to 80ffdda44c)