pola-rs/polars · error · ValueError

`label` is required if setting `features` when `return_type=

Error message

`label` is required if setting `features` when `return_type='dict'

What it means

Raised by DataFrame.to_jax(return_type='dict') when `features` is given but `label` is None. The dict export builds its split around the label column (features default to 'everything except label'), so features without a label has no well-defined split. Polars requires the symmetric pairing: either both label and features, label alone, or neither.

Source

Thrown at py-polars/src/polars/dataframe/frame.py:2238

        ...     return_type="dict",
        ...     features=cs.float(),
        ...     label=pl.col("lbl").cast(pl.UInt8),
        ... )
        {'label': Array([[0],
                [1],
                [2],
                [3]], dtype=uint8),
         'features': Array([[ 1.5 ],
                [-0.5 ],
                [ 0.  ],
                [-2.25]], dtype=float32)}
        """
        if return_type != "dict" and (label is not None or features is not None):
            msg = "`label` and `features` only apply when `return_type` is 'dict'"
            raise ValueError(msg)
        elif return_type == "dict" and label is None and features is not None:
            msg = "`label` is required if setting `features` when `return_type='dict'"
            raise ValueError(msg)

        jx = import_optional(
            "jax",
            install_message="Please see `https://jax.readthedocs.io/en/latest/installation.html` "
            "for specific installation recommendations for the Jax package",
        )
        enabled_double_precision = jx.config.jax_enable_x64 or bool(
            int(os.environ.get("JAX_ENABLE_X64", "0"))
        )
        if dtype:
            frame = self.cast(dtype)
        elif not enabled_double_precision:
            # enforce single-precision unless environment/config directs otherwise
            frame = self.cast({Float64: Float32, Int64: Int32, UInt64: UInt32})
        else:
            frame = self

        if isinstance(device, str):

View on GitHub (pinned to df599052da)

Solutions

Provide a label: `df.to_jax('dict', label='y', features=['a','b'])`
If there is no label, use plain column selection: `df.select(['a','b']).to_jax()` or `df.to_jax('dict', label='y')` only
Guard kwargs construction: only include features when label is also present

Example fix

# before
out = df.to_jax('dict', features=['f1', 'f2'])

# after
out = df.select(['f1', 'f2']).to_jax()   # no label concept needed

Defensive patterns

Strategy: validation

Validate before calling

if return_type == 'dict' and features is not None and label is None:
    raise ValueError('to_jax dict export needs a label when features are given')
out = df.to_jax(return_type, label=label, features=features)

Try / catch

try:
    out = df.to_jax('dict', label=label, features=features)
except ValueError as e:
    if '`label` is required' in str(e):
        out = df.select(features or df.columns).to_jax()
    else:
        raise

Prevention

Treat label and features as a pair for dict exports: set both or just label
For label-free exports, select columns and call to_jax() without split args
Centralize model-export config so the label/features pairing is validated once

When it happens

Trigger: `df.to_jax('dict', features=['a','b'])` with no label; passing label=None explicitly with a features list; building kwargs dynamically where the label entry is omitted on some code path.

Common situations: Unsupervised-learning code paths reusing a supervised export helper and only setting features; feature lists computed from column names where the label variable is accidentally None; config-driven pipelines where 'label' is optional but 'features' is always set.

Related errors

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/435a03029cf59bba. Report an issue: GitHub.