pola-rs/polars · error · RuntimeError

unknown feature flag

Error message

unknown feature flag: {f!r}

What it means

`check_cpu_flags` validates that every expected CPU feature name is a known key in the supported-flag map read from the CPU. If a caller passes a flag string the reader never produces (e.g. misspelled or platform-inappropriate), it raises `RuntimeError("unknown feature flag: ...")`. This is a programming/API-misuse check, not a hardware-shortage report (missing features produce a different warning path).

Solutions

1. Correct the feature-flag name to one in the supported set (e.g. `sse3`, `avx`, `avx2`, depending on platform).
2. Inspect the keys of `_read_cpu_flags()` output on your platform to see valid flag names.
3. Make the flag list platform-conditional instead of hard-coding it.

Example fix

// before
check_cpu_flags(['avx512_bf16'])  # unknown on this platform

// after
check_cpu_flags(['avx2'])  # a flag present in supported_cpu_flags

supported = _read_cpu_flags()
flags = [f for f in wanted_flags if f in supported]

def known_flags(flags: list[str]) -> list[str]:
    supported = _read_cpu_flags()
    return [f for f in flags if f in supported]

try:
    check_cpu_flags(expected)
except RuntimeError as e:
    if 'unknown feature flag' in str(e):
        expected = [f for f in expected if f in supported_cpu_flags]
    else:
        raise

When it happens

Trigger: Calling `check_cpu_flags(['avx123'])` or similar with a typo'd/unsupported feature name; polars' own `rt_64`/`rt_32`/`rt_compat` helpers passing a flag set invalid on the current platform; tests probing unknown flags.

Common situations: Custom build scripts or environment configuration specifying CPU features; developers extending polars' runtime feature checks with mistyped flag names.

Understand the failure class

Background: "unknown output mode", "invalid value for flag", "expects true/false": fixing invalid flag value errors in CLI tools — this error's family across 24 libraries.

Related errors

• cannot use credential_provider when passing a DeltaTable…
• `format` must be one of
• `how` must be one of
• invalid input for `aggregate_function` argument
• invalid input for shape

AI-assisted analysis of pola-rs/polars@fe841f959e (2026-09-18). Data as JSON: /api/errors/b87a190296e8ce6a. Report an issue: GitHub.

Appendix: source

Thrown at py-polars/src/polars/_cpu_check.py:263

    expected_cpu_flags = [
        f.lstrip("+") for f in feature_flags.split(",") if not f.startswith("-")
    ]
    expected_cpu_flags = [
        f
        for f in expected_cpu_flags
        if f and f != "ctr-static"  # Not actually a CPU flag.
    ]

    if not expected_cpu_flags or os.environ.get("POLARS_SKIP_CPU_CHECK"):
        return

    supported_cpu_flags = _read_cpu_flags()

    missing_features = []
    for f in expected_cpu_flags:
        if f not in supported_cpu_flags:
            msg = f"unknown feature flag: {f!r}"
            raise RuntimeError(msg)

        if not supported_cpu_flags[f]:
            missing_features.append(f)

    if missing_features:
        import warnings  # Only import if necessary.

        warnings.warn(
            f"""Missing required CPU features.

The following required CPU features were not detected:
    {", ".join(missing_features)}
Continuing to use this version of Polars on this processor will likely result in a crash.
Install `polars[rtcompat]` instead of `polars` to run Polars with better compatibility.

Hint: If you are on an Apple ARM machine (e.g. M1) this is likely due to running Python under Rosetta.
It is recommended to install a native version of Python that does not run under Rosetta x86-64 emulation.

View on GitHub (pinned to fe841f959e)