HKUDS/Vibe-Trading · error · ValueError

unknown panel column: {column}

Error message

unknown panel column: {column}

What it means

validate_columns_required checks that every column a factor declares is either a known price column (in _PRICE_COLS) or a fund-prefixed column ('fund:...'). Any other column name raises ValueError because the panel builder would not know how to supply it.

Source

Thrown at agent/src/factors/registry.py:84

Universe = Literal["equity_us", "equity_cn", "equity_hk", "equity_in", "equity_kr", "crypto", "futures"]


def validate_columns_required(cols: list[str]) -> None:
    """Validate required panel columns for alpha metadata.

    Args:
        cols: Declared panel columns from ``__alpha_meta__``.

    Raises:
        ValueError: If a column is neither a known price column nor a
            ``fund:``-prefixed fundamental column.
    """
    for column in cols:
        if column in _PRICE_COLS:
            continue
        if column.startswith("fund:"):
            continue
        raise ValueError(f"unknown panel column: {column}")


class AlphaMeta(BaseModel):
    """Strict metadata schema; matches the ``__alpha_meta__`` dict literal."""

    model_config = ConfigDict(extra="forbid", frozen=True)

    id: str = Field(pattern=r"^[a-z][a-z0-9]+_[a-z0-9_]+$")
    nickname: str | None = None
    theme: list[Theme]
    formula_latex: str
    columns_required: list[PanelColumn]
    extras_required: list[str] = Field(default_factory=list)
    requires_sector: bool = False
    universe: list[Universe]
    frequency: list[str]
    decay_horizon: int = Field(ge=0, le=512)
    min_warmup_bars: int = Field(ge=0)

View on GitHub (pinned to 80ffdda44c)

Solutions

1. Fix the column name to match a known _PRICE_COLS entry
2. Use the 'fund:' prefix if it is fundamental data
3. Extend _PRICE_COLS in the registry if a genuinely new column type is supported by your panel builder

Example fix

# before
__alpha_meta__ = {..., 'columns': ['turnover']}
# after
__alpha_meta__ = {..., 'columns': ['fund:turnover']}

from factors.registry import _PRICE_COLS
bad = [c for c in cols if c not in _PRICE_COLS and not c.startswith('fund:')]
assert not bad, f'unknown columns: {bad}'

def is_known_column(c: str) -> bool:
    return c in _PRICE_COLS or c.startswith('fund:')

try:
    validate_columns_required(cols)
except ValueError as e:
    raise ConfigError(f'factor spec rejected: {e}') from e

When it happens

Trigger: Declaring a column like 'turnover' or 'pe_ratio' in a factor's required columns when it is not in _PRICE_COLS and lacks the 'fund:' prefix.

Common situations: Adding a new factor that depends on an unsupported data field, typos in column names ('Close' vs 'close'), or forgetting the fund: namespace for fundamental data.

Related errors

• invalid {kind} {token!r}: must match {_ID_RE.pattern}
• {path.name}: {size}B exceeds {_MAX_PY_BYTES}B cap
• {path.name}: __alpha_meta__ assignment not found
• {path.name}: __alpha_meta__ not a literal: {exc}
• {path.name}: __alpha_meta__ must be dict, got {type(raw).__n

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