HKUDS/Vibe-Trading · error · ValueError

kind is required and cannot be empty

Error message

kind is required and cannot be empty

What it means

Raised by CashFlow normalize_kind when, after stripping and normalizing, the label is empty — the input was blank, only separators ('-', ' ', '_'), or became empty after collapse. kind is a required discriminator for cash-flow categorization, so blank values are rejected.

Source

Thrown at agent/src/entities/cashflow.py:117

    actually bites on those files instead of silently treating each spelling as
    an unconstrained custom kind.

    Args:
        value: Raw kind label from a caller or a file.

    Returns:
        Lower-cased label with spaces and hyphens collapsed to underscores.

    Raises:
        ValueError: If the label is not a string or is blank.
    """
    if not isinstance(value, str):
        raise ValueError(f"kind must be a string, got {type(value).__name__}")
    cleaned = value.strip().lower().replace("-", "_").replace(" ", "_")
    while "__" in cleaned:
        cleaned = cleaned.replace("__", "_")
    if not cleaned:
        raise ValueError("kind is required and cannot be empty")
    return cleaned


@dataclass(frozen=True)
class CashFlow:
    """A single dated cash amount in one currency.

    Attributes:
        date: Settlement date. ``datetime`` and ISO-8601 strings are accepted
            and normalized to ``datetime.date``.
        amount: Signed amount, positive into the holder. See the module
            docstring for the convention and its enforcement.
        kind: Canonical kind label, e.g. ``"capital_call"`` or ``"coupon"``.
            Normalized via ``normalize_kind``.
        currency: Required currency code, normalized to uppercase.
        metadata: Free-form extra fields, exposed as a read-only mapping so the
            flow stays immutable. Ingestion puts unmapped file columns here
            rather than discarding them.

View on GitHub (pinned to 80ffdda44c)

Solutions

1. Supply a meaningful label, e.g. 'dividend' or 'wire_in'.
2. Skip or filter out rows with blank kind before constructing cash-flow entities.
3. Map blank incoming labels to an explicit 'unknown' category if you must ingest them.

Example fix

# before
normalize_kind('  ')

# after
normalize_kind('wire_in')

def kind_nonblank(value: str) -> bool:
    import re
    return bool(re.sub(r'[_\s-]+', '', str(value or '')))

def is_valid_kind(value) -> bool:
    return isinstance(value, str) and bool(value.strip()) and bool(value.strip().replace('_', '').replace('-', ''))

When it happens

Trigger: normalize_kind(''), normalize_kind(' '), normalize_kind('---') or '__' — all reduce to an empty string after cleaning.

Common situations: Empty spreadsheet cells or CSV columns parsed as ''; forms submitted with whitespace-only labels; default '' placeholders in data pipelines.

Related errors

• kind must be a string, got {type(value).__name__}
• amount must be a finite number, got {self.amount!r}; a missi
• kind={self.kind!r} must have a {direction} amount under the
• pre_translated=True asserts the flows were already converted
• start {lower} is after end {upper}

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