{"record":{"id":"cb110d0e6efd7ab5","repo":"python/cpython","slug":"check-hash-based-pycs-must-be-one-of-default","errorCode":null,"errorMessage":"--check-hash-based-pycs must be one of 'default', 'always', or 'never'\\n","messagePattern":"--check-hash-based-pycs must be one of 'default', 'always', or 'never'\\\\n","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"Python/initconfig.c","lineNumber":3148,"sourceCode":"            }\n            break;\n        }\n\n        switch (c) {\n        // Integers represent long options, see Python/getopt.c\n        case 0:\n            // check-hash-based-pycs\n            if (wcscmp(_PyOS_optarg, L\"always\") == 0\n                || wcscmp(_PyOS_optarg, L\"never\") == 0\n                || wcscmp(_PyOS_optarg, L\"default\") == 0)\n            {\n                status = PyConfig_SetString(config, &config->check_hash_pycs_mode,\n                                            _PyOS_optarg);\n                if (_PyStatus_EXCEPTION(status)) {\n                    return status;\n                }\n            } else {\n                fprintf(stderr, \"--check-hash-based-pycs must be one of \"\n                        \"'default', 'always', or 'never'\\n\");\n                config_usage(1, program);\n                return _PyStatus_EXIT(2);\n            }\n            break;\n\n        case 1:\n            // help-all\n            config_complete_usage(program);\n            return _PyStatus_EXIT(0);\n\n        case 2:\n            // help-env\n            config_envvars_usage();\n            return _PyStatus_EXIT(0);\n\n        case 3:\n            // help-xoptions","sourceCodeStart":3130,"sourceCodeEnd":3166,"githubUrl":"https://github.com/python/cpython/blob/bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6/Python/initconfig.c#L3130-L3166","documentation":"Emitted by CPython startup (Python/initconfig.c, config_parse_cmdline) when the value given to --check-hash-based-pycs is not one of the three accepted strings 'default', 'always', or 'never'. After printing the message the interpreter prints usage and exits with status 2 via _PyStatus_EXIT(2), before any user code runs.","triggerScenarios":"Running `python --check-hash-based-pycs=sometimes script.py` or `--check-hash-based-pycs always/never` (invalid token). Any value failing the wcscmp checks against L\"always\", L\"never\", L\"default\".","commonSituations":"Misremembering the allowed values (e.g. 'true'/'false', '1'/'0'); passing an empty variable; configuration copied from tools with different vocabulary; shell scripts forwarding a user-provided mode string unchecked.","solutions":["Use one of the exact tokens: default, always, or never — e.g. `python --check-hash-based-pycs=always script.py`","Validate the value in wrapper scripts before launching python","Note the equivalent env/config knob: sys.flags.check_hash_pycs_mode and PYTHONPYCACHEPREFIX alternatives for cache-control use cases"],"exampleFix":"# before\npython --check-hash-based-pycs=on script.py\n# after\npython --check-hash-based-pycs=always script.py","handlingStrategy":"validation","validationCode":"# bash\nMODE=\"${PYC_MODE:-default}\"\ncase \"$MODE\" in default|always|never) ;; *) echo \"bad mode: $MODE\" >&2; exit 2;; esac\npython --check-hash-based-pycs=\"$MODE\" app.py","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Whitelist the value (default|always|never) in any wrapper that forwards it","Read the exit status: the interpreter exits 2 on this error, so scripts can detect it","Document allowed values wherever the flag is exposed to users"],"tags":["cli","cpython","pyc","validation","startup"],"backgroundTag":null,"analyzedSha":"bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6","analyzedAt":"2026-08-14T22:01:13.976Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}