HKUDS/Vibe-Trading · error · ValueError

unknown structure {self.structure!r}; expected one of: {vali

Error message

unknown structure {self.structure!r}; expected one of: {valid}

What it means

Fund.__post_init__ validates the structure field against the FundStructure enum; a string that is not an exact member value raises ValueError listing valid structures (e.g. open-ended vs closed-ended).

Source

Thrown at agent/src/entities/models.py:304

    structure: FundStructure = FundStructure.CLOSED_END
    strategy: str = ""
    commitment: float | None = None
    management_fee_rate: float | None = None

    def __post_init__(self) -> None:
        """Validate the base fields plus fund-specific ranges.

        Raises:
            ValueError: If ``structure`` is unknown, ``commitment`` is
                negative, ``management_fee_rate`` is out of ``[0, 1]``, or
                ``vintage_year`` is implausible.
        """
        super().__post_init__()
        try:
            object.__setattr__(self, "structure", FundStructure(self.structure))
        except ValueError as exc:
            valid = ", ".join(member.value for member in FundStructure)
            raise ValueError(
                f"unknown structure {self.structure!r}; expected one of: {valid}"
            ) from exc
        if self.vintage_year is not None and not 1800 <= int(self.vintage_year) <= 2200:
            raise ValueError(
                f"vintage_year={self.vintage_year!r} is outside the plausible "
                "range 1800-2200"
            )
        if self.commitment is not None:
            if float(self.commitment) < 0:
                raise ValueError(
                    f"commitment must be non-negative (it is a size, not a signed "
                    f"cash flow), got {self.commitment!r}"
                )
            object.__setattr__(self, "commitment", float(self.commitment))
        if self.management_fee_rate is not None:
            rate = float(self.management_fee_rate)
            if not 0.0 <= rate <= 1.0:
                raise ValueError(

View on GitHub (pinned to 80ffdda44c)

Solutions

Use a FundStructure member or its exact value
Normalize structure strings (strip/case-fold) and map aliases before construction
Extend FundStructure if a legitimate structure variant is missing

Example fix

# before
Fund(instrument_id='f1', structure='open-ended')

# after
Fund(instrument_id='f1', structure=FundStructure.OPEN_ENDED.value)

Defensive patterns

Strategy: validation

Validate before calling

from agent.src.entities.models import FundStructure
structure = row['structure'].strip().lower()
structure = {'open-ended': FundStructure.OPEN_ENDED.value, ...}.get(structure, structure)
FundStructure(structure)  # raises early with your own context if still bad

Type guard

from agent.src.entities.models import FundStructure

def is_valid_fund_structure(v: str) -> bool:
    try:
        FundStructure(v)
        return True
    except ValueError:
        return False

Try / catch

try:
    f = Fund(instrument_id=iid, structure=structure, ...)
except ValueError as exc:
    if 'unknown structure' in str(exc):
        log.warning('bad fund structure %r on %s', structure, iid)
        continue
    raise

Prevention

Map prose fund-structure labels to canonical enum values before loading
Validate once during data-profiling, not per object in production loops

When it happens

Trigger: Fund(..., structure='Open Ended'), structure='closed' (abbreviation), or any typo/whitespace variant. The enum call happens after super().__post_init__(), so instrument-level validation has already passed.

Common situations: Fund reference data sourced from documents or spreadsheets using prose labels; a data vendor that abbreviates structures; enum renames between releases leaving stale stored values.

Related errors

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