{"record":{"id":"b87a190296e8ce6a","repo":"pola-rs/polars","slug":"unknown-feature-flag-f-r","errorCode":null,"errorMessage":"unknown feature flag: {f!r}","messagePattern":"unknown feature flag: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/_cpu_check.py","lineNumber":263,"sourceCode":"    expected_cpu_flags = [\n        f.lstrip(\"+\") for f in feature_flags.split(\",\") if not f.startswith(\"-\")\n    ]\n    expected_cpu_flags = [\n        f\n        for f in expected_cpu_flags\n        if f and f != \"ctr-static\"  # Not actually a CPU flag.\n    ]\n\n    if not expected_cpu_flags or os.environ.get(\"POLARS_SKIP_CPU_CHECK\"):\n        return\n\n    supported_cpu_flags = _read_cpu_flags()\n\n    missing_features = []\n    for f in expected_cpu_flags:\n        if f not in supported_cpu_flags:\n            msg = f\"unknown feature flag: {f!r}\"\n            raise RuntimeError(msg)\n\n        if not supported_cpu_flags[f]:\n            missing_features.append(f)\n\n    if missing_features:\n        import warnings  # Only import if necessary.\n\n        warnings.warn(\n            f\"\"\"Missing required CPU features.\n\nThe following required CPU features were not detected:\n    {\", \".join(missing_features)}\nContinuing to use this version of Polars on this processor will likely result in a crash.\nInstall `polars[rtcompat]` instead of `polars` to run Polars with better compatibility.\n\nHint: If you are on an Apple ARM machine (e.g. M1) this is likely due to running Python under Rosetta.\nIt is recommended to install a native version of Python that does not run under Rosetta x86-64 emulation.\n","sourceCodeStart":245,"sourceCodeEnd":281,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/py-polars/src/polars/_cpu_check.py#L245-L281","documentation":"`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).","triggerScenarios":"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.","commonSituations":"Custom build scripts or environment configuration specifying CPU features; developers extending polars' runtime feature checks with mistyped flag names.","solutions":["Correct the feature-flag name to one in the supported set (e.g. `sse3`, `avx`, `avx2`, depending on platform).","Inspect the keys of `_read_cpu_flags()` output on your platform to see valid flag names.","Make the flag list platform-conditional instead of hard-coding it."],"exampleFix":"// before\ncheck_cpu_flags(['avx512_bf16'])  # unknown on this platform\n\n// after\ncheck_cpu_flags(['avx2'])  # a flag present in supported_cpu_flags","handlingStrategy":"validation","validationCode":"supported = _read_cpu_flags()\nflags = [f for f in wanted_flags if f in supported]","typeGuard":"def known_flags(flags: list[str]) -> list[str]:\n    supported = _read_cpu_flags()\n    return [f for f in flags if f in supported]","tryCatchPattern":"try:\n    check_cpu_flags(expected)\nexcept RuntimeError as e:\n    if 'unknown feature flag' in str(e):\n        expected = [f for f in expected if f in supported_cpu_flags]\n    else:\n        raise","preventionTips":["Source feature-flag names from `_read_cpu_flags()` keys rather than hard-coding strings.","Keep the flag list platform-conditional (x86-only features differ from ARM).","Add a unit test that validates every configured flag against the supported set."],"tags":["python","polars","cpu-flags","invalid-argument"],"backgroundTag":"invalid-flag-value","analyzedSha":"fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e","analyzedAt":"2026-09-18T22:14:11.667Z","contentChangedAt":"2026-09-18T22:14:11.667Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}