{"record":{"id":"2d826ad441d59efa","repo":"pandas-dev/pandas","slug":"option-key-is-a-prefix-of-an-already-registere","errorCode":null,"errorMessage":"Option '{key}' is a prefix of an already-registered option","messagePattern":"Option '(.+?)' is a prefix of an already-registered option","errorType":"exception","errorClass":"OptionError","httpStatus":null,"severity":"error","filePath":"pandas/_config/config.py","lineNumber":595,"sourceCode":"\n    cursor = _global_config\n    msg = \"Path prefix to option '{option}' is already an option\"\n\n    for i, p in enumerate(path[:-1]):\n        if not isinstance(cursor, dict):\n            raise OptionError(msg.format(option=\".\".join(path[:i])))\n        if p not in cursor:\n            cursor[p] = {}\n        cursor = cursor[p]\n\n    if not isinstance(cursor, dict):\n        raise OptionError(msg.format(option=\".\".join(path[:-1])))\n\n    # a namespace already lives here, i.e. `key` is a path prefix to one or\n    # more already-registered options; registering it would clobber them\n    # (GH#29242)\n    if isinstance(cursor.get(path[-1]), dict):\n        raise OptionError(f\"Option '{key}' is a prefix of an already-registered option\")\n\n    cursor[path[-1]] = defval  # initialize\n\n    # save the option metadata\n    _registered_options[key] = RegisteredOption(\n        key=key, defval=defval, doc=doc, validator=validator, cb=cb\n    )\n\n\ndef deprecate_option(\n    key: str,\n    category: type[Warning],\n    msg: str | None = None,\n    rkey: str | None = None,\n    removal_ver: str | None = None,\n) -> None:\n    \"\"\"\n    Mark option `key` as deprecated, if code attempts to access this option,","sourceCodeStart":577,"sourceCodeEnd":613,"githubUrl":"https://github.com/pandas-dev/pandas/blob/71959b8cb9b2459c16e14b34f28b178ccfe14735/pandas/_config/config.py#L577-L613","documentation":"Raised by register_option (config.py:594-595) when the final segment of the new key already maps to a dict in the cursor — i.e. the new key is a prefix of an already-registered option and would clobber a subtree (GH#29242). The check uses isinstance(cursor.get(path[-1]), dict).","triggerScenarios":"cf.register_option('display', 1) when 'display.max_columns' etc. already exist; registering a parent that shadows existing children.","commonSituations":"Trying to 'simplify' the namespace by registering a short key that is already a namespace.","solutions":["Register under a different top-level name that is not already a subtree.","Use the existing leaf option under that namespace via set_option.","Inspect the existing subtree (pd.describe_option('prefix')) before registering."],"exampleFix":"# before\ncf.register_option('display', 1)  # prefix of already-registered option\n\n# after\ncf.register_option('myapp.display', 1)","handlingStrategy":"validation","validationCode":"import pandas._config.config as cf\ndef is_not_prefix(key: str) -> bool:\n    cursor = cf._global_config\n    for seg in key.lower().split('.')[:-1]:\n        cursor = cursor.get(seg, {})\n    return not isinstance(cursor.get(key.split('.')[-1]), dict)","typeGuard":null,"tryCatchPattern":"from pandas.errors import OptionError\ntry:\n    cf.register_option(key, defval)\nexcept OptionError:\n    cf.register_option(renamed_key, defval)","preventionTips":["Never register a key that is a prefix of existing keys.","Run pd.describe_option(key) to confirm a key is a namespace before attempting leaf registration.","Choose a distinct top-level prefix for each library's options."],"tags":["config","register-option","prefix-conflict"],"analyzedSha":"71959b8cb9b2459c16e14b34f28b178ccfe14735","analyzedAt":"2026-08-07T01:30:20.476Z","schemaVersion":2},"datasetVersion":"2026-08-07T03:17:09.362Z"}