{"record":{"id":"0577a84b171899f4","repo":"ansible/ansible","slug":"internal-error-required-and-default-are-mutually","errorCode":null,"errorMessage":"internal error: required and default are mutually exclusive for %s","messagePattern":"internal error: required and default are mutually exclusive for (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"lib/ansible/module_utils/common/parameters.py","lineNumber":232,"sourceCode":"    :param alias_deprecations:\n    :type alias_deprecations: list\n    \"\"\"\n\n    aliases_results = {}  # alias:canon\n\n    for (k, v) in argument_spec.items():\n        aliases = v.get('aliases', None)\n        default = v.get('default', None)\n        required = v.get('required', False)\n\n        if alias_deprecations is not None:\n            for alias in argument_spec[k].get('deprecated_aliases', []):\n                if alias.get('name') in parameters:\n                    alias_deprecations.append(alias)\n\n        if default is not None and required:\n            # not alias specific but this is a good place to check this\n            raise ValueError(\"internal error: required and default are mutually exclusive for %s\" % k)\n\n        if aliases is None:\n            continue\n\n        if not is_iterable(aliases) or isinstance(aliases, (bytes, str)):\n            raise TypeError('internal error: aliases must be a list or tuple')\n\n        for alias in aliases:\n            aliases_results[alias] = k\n            if alias in parameters:\n                if k in parameters and alias_warnings is not None:\n                    alias_warnings.append((k, alias))\n                parameters[k] = parameters[alias]\n\n    return aliases_results\n\n\ndef _list_deprecations(argument_spec, parameters, prefix=''):","sourceCodeStart":214,"sourceCodeEnd":250,"githubUrl":"https://github.com/ansible/ansible/blob/9cf16a4aca7898481c257f1e17ad28d0b67b1f85/lib/ansible/module_utils/common/parameters.py#L214-L250","documentation":"Raised by _handle_aliases() in ansible.module_utils.common.parameters with ValueError when an argument_spec entry declares both required=True and a non-None default. These are mutually exclusive because a required parameter must always be supplied by the user, so a default can never apply. The 'internal error' prefix signals a bug in the module's own spec, not user input.","triggerScenarios":"Defining argument_spec = {'name': {'required': True, 'default': 'x'}} and instantiating AnsibleModule. Note the check uses `default is not None`, so default=None with required=True is allowed.","commonSituations":"Module authors adding a default for convenience after previously marking a param required; copy-paste of spec entries; third-party or collection modules with untested spec combinations.","solutions":["Decide the semantics: if the value is truly required, remove the default","If a sensible fallback exists, remove required: true and keep the default","Add a unit test that instantiates the module (or validates the spec) so spec errors fail in CI, not on the target host"],"exampleFix":"# before\nargument_spec = dict(\n    path=dict(type='str', required=True, default='/tmp'),\n)\n\n# after\nargument_spec = dict(\n    path=dict(type='str', default='/tmp'),\n)","handlingStrategy":"validation","validationCode":"for name, spec in argument_spec.items():\n    if spec.get('required') and spec.get('default') is not None:\n        raise AssertionError(f'{name}: required and default are mutually exclusive')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never combine required=True with a default in argument_spec","Cover specs with unit tests / ansible-test sanity validate-modules before release","Remember default=None with required=True is legal; only non-None defaults conflict"],"tags":["argument-spec","module-authoring","validation","ansible-module-utils"],"backgroundTag":null,"analyzedSha":"9cf16a4aca7898481c257f1e17ad28d0b67b1f85","analyzedAt":"2026-08-15T00:15:47.100Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}