{"id":"b02163d1282b3301","repo":"pypa/pip","slug":"key-does-not-contain-dot-separated-section-and-key","errorCode":null,"errorMessage":"Key does not contain dot separated section and key. Perhaps you wanted to use 'global.{name}' instead?","messagePattern":"Key does not contain dot separated section and key\\. Perhaps you wanted to use 'global\\.(.+?)' instead\\?","errorType":"exception","errorClass":"ConfigurationError","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/configuration.py","lineNumber":65,"sourceCode":"\nlogger = getLogger(__name__)\n\n\n# NOTE: Maybe use the optionx attribute to normalize keynames.\ndef _normalize_name(name: str) -> str:\n    \"\"\"Make a name consistent regardless of source (environment or file)\"\"\"\n    name = name.lower().replace(\"_\", \"-\")\n    name = name.removeprefix(\"--\")  # only prefer long opts\n    return name\n\n\ndef _disassemble_key(name: str) -> list[str]:\n    if \".\" not in name:\n        error_message = (\n            \"Key does not contain dot separated section and key. \"\n            f\"Perhaps you wanted to use 'global.{name}' instead?\"\n        )\n        raise ConfigurationError(error_message)\n    return name.split(\".\", 1)\n\n\ndef get_configuration_files() -> dict[Kind, list[str]]:\n    global_config_files = [\n        os.path.join(path, CONFIG_BASENAME) for path in appdirs.site_config_dirs(\"pip\")\n    ]\n\n    site_config_file = os.path.join(sys.prefix, CONFIG_BASENAME)\n    legacy_config_file = os.path.join(\n        os.path.expanduser(\"~\"),\n        \"pip\" if WINDOWS else \".pip\",\n        CONFIG_BASENAME,\n    )\n    new_config_file = os.path.join(appdirs.user_config_dir(\"pip\"), CONFIG_BASENAME)\n    return {\n        kinds.GLOBAL: global_config_files,\n        kinds.SITE: [site_config_file],","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/pypa/pip/blob/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_internal/configuration.py#L47-L83","documentation":"Raised as ConfigurationError in _disassemble_key() at configuration.py:60-65 when the provided config key has no '.' separator. pip's config API requires keys in 'section.name' form (e.g. 'global.index-url'); a bare name like 'index-url' is ambiguous and pip suggests prefixing it with a section such as 'global.'.","triggerScenarios":"Calling pip config get/set/unset with a key that contains no dot, e.g. 'pip config set index-url https://...'. _disassemble_key is invoked from get_value (configuration.py:156), set_value (configuration.py:168), and unset_value (configuration.py:195).","commonSituations":"New users unfamiliar with the section.key convention; forgetting the 'global.' / 'install.' / 'user.' prefix; copying an option name directly from documentation into 'pip config set'.","solutions":["Prefix the key with its section, e.g. 'global.index-url' or 'install.no-index'.","Use 'pip config list' to see existing keys and their section prefixes.","Consult 'pip config --help' for the section.name format."],"exampleFix":"# before\npip config set index-url https://pypi.org/simple\n# after\npip config set global.index-url https://pypi.org/simple","handlingStrategy":"validation","validationCode":"def validate_config_key(key: str) -> None:\n    if '.' not in key:\n        raise ValueError(\n            f\"pip config key must be 'section.name'; got {key!r}. \"\n            f\"Try 'global.{key}'.\"\n        )\n\nvalidate_config_key('index-url')  # raises with a helpful message","typeGuard":"def is_sectioned_config_key(key: str) -> bool:\n    \"\"\"True if key has the required 'section.name' form for pip config.\"\"\"\n    return isinstance(key, str) and '.' in key and all(key.split('.', 1))","tryCatchPattern":null,"preventionTips":["Always use 'section.name' form (e.g. 'global.index-url', 'install.no-index') for pip config keys.","Use 'pip config list' to learn the canonical key names and their section prefixes.","Validate keys in wrapper scripts before passing them to 'pip config set/get/unset'."],"tags":["pip","config","configuration","key-format"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}