{"id":"2a3572c53a51e94c","repo":"pypa/pip","slug":"needed-a-specific-file-to-be-modifying","errorCode":null,"errorMessage":"Needed a specific file to be modifying.","messagePattern":"Needed a specific file to be modifying\\.","errorType":"exception","errorClass":"ConfigurationError","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/configuration.py","lineNumber":239,"sourceCode":"            ensure_dir(os.path.dirname(fname))\n\n            # Ensure directory's permission(need to be writeable)\n            try:\n                with open(fname, \"w\") as f:\n                    parser.write(f)\n            except OSError as error:\n                raise ConfigurationError(\n                    f\"An error occurred while writing to the configuration file \"\n                    f\"{fname}: {error}\"\n                )\n\n    #\n    # Private routines\n    #\n\n    def _ensure_have_load_only(self) -> None:\n        if self.load_only is None:\n            raise ConfigurationError(\"Needed a specific file to be modifying.\")\n        logger.debug(\"Will be working with %s variant only\", self.load_only)\n\n    @property\n    def _dictionary(self) -> dict[str, dict[str, Any]]:\n        \"\"\"A dictionary representing the loaded configuration.\"\"\"\n        # NOTE: Dictionaries are not populated if not loaded. So, conditionals\n        #       are not needed here.\n        retval = {}\n\n        for variant in OVERRIDE_ORDER:\n            retval.update(self._config[variant])\n\n        return retval\n\n    def _load_config_files(self) -> None:\n        \"\"\"Loads configuration from configuration files\"\"\"\n        config_files = dict(self.iter_config_files())\n        if config_files[kinds.ENV][0:1] == [os.devnull]:","sourceCodeStart":221,"sourceCodeEnd":257,"githubUrl":"https://github.com/pypa/pip/blob/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_internal/configuration.py#L221-L257","documentation":"Raised as ConfigurationError in Configuration._ensure_have_load_only() at configuration.py:237-239 when load_only is None and a mutating operation (set_value, unset_value, or save) is attempted. pip needs to know WHICH config file to modify, so a Configuration constructed without a load_only cannot target a file for writes.","triggerScenarios":"Calling Configuration.set_value/unset_value/save on an instance built with load_only=None. _ensure_have_load_only is called at the top of set_value (configuration.py:162), unset_value (configuration.py:183), and save (configuration.py:215). Programmatic/internal usage that forgets to scope the Configuration to a single variant.","commonSituations":"Internal tooling that constructs Configuration(isolated=False) without load_only and then tries to write; misuse of pip's internal Configuration API outside the CLI's normal 'pip config set --user/--global/--site' flow.","solutions":["Construct Configuration with a concrete load_only ('user', 'global', or 'site') before calling mutating methods.","Use the 'pip config set/unset' CLI which always supplies the correct load_only from the --user/--global/--site flag.","Separate read-only usage (load_only=None is fine for reads) from write usage (load_only required)."],"exampleFix":"# before\ncfg = Configuration(isolated=False)  # load_only=None\ncfg.set_value('global.index-url', 'https://...')  # raises\n# after\ncfg = Configuration(isolated=False, load_only='user')\ncfg.load()\ncfg.set_value('global.index-url', 'https://...')\ncfg.save()","handlingStrategy":"type-guard","validationCode":"from pip._internal.configuration import Configuration, VALID_LOAD_ONLY\n\ndef writable_config(load_only):\n    if load_only is None:\n        raise ValueError('load_only is required for mutating operations; pass user/global/site')\n    if load_only not in VALID_LOAD_ONLY:\n        raise ValueError(f'load_only must be one of {VALID_LOAD_ONLY}')\n    return Configuration(isolated=False, load_only=load_only)\n\ncfg = writable_config('user')","typeGuard":"from pip._internal.configuration import VALID_LOAD_ONLY\n\ndef is_ready_for_writes(cfg) -> bool:\n    return getattr(cfg, 'load_only', None) in VALID_LOAD_ONLY","tryCatchPattern":null,"preventionTips":["Always construct Configuration with a concrete load_only ('user','global','site') when you intend to set/unset/save.","Prefer the 'pip config' CLI which sets load_only from --user/--global/--site.","Keep read-only Configuration instances (load_only=None) separate from write instances."],"tags":["pip","config","configuration","missing-load-only","internal-api"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}