You are reading an unmaintained version of the Ansible documentation. Unmaintained Ansible versions can contain unfixed security vulnerabilities (CVE). Please upgrade to a maintained version. See the latest Ansible documentation.

validate-modules

Analyze modules for common issues in code and documentation.

Usage 

cd /path/to/ansible/source
source hacking/env-setup
ansible-test sanity --test validate-modules

Help 

Type ansible-test sanity --test validate-modules -h to display help for using this sanity test.

Extending validate-modules 

The validate-modules tool has a schema.py that is used to validate the YAML blocks, such as DOCUMENTATION and RETURNS.

Codes 

Error Code	Type	Level	Sample Message
ansible-deprecated-module	Documentation	Error	A module is deprecated and supposed to be removed in the current or an earlier Ansible version
collection-deprecated-module	Documentation	Error	A module is deprecated and supposed to be removed in the current or an earlier collection version
ansible-deprecated-version	Documentation	Error	A feature is deprecated and supposed to be removed in the current or an earlier Ansible version
ansible-module-not-initialized	Syntax	Error	Execution of the module did not result in initialization of AnsibleModule
collection-deprecated-version	Documentation	Error	A feature is deprecated and supposed to be removed in the current or an earlier collection version
deprecated-date	Documentation	Error	A date before today appears as `removed_at_date` or in `deprecated_aliases`
deprecation-mismatch	Documentation	Error	Module marked as deprecated or removed in at least one of the filename, its metadata, or in DOCUMENTATION (setting DOCUMENTATION.deprecated for deprecation or removing all Documentation for removed) but not in all three places.
doc-choices-do-not-match-spec	Documentation	Error	Value for “choices” from the argument_spec does not match the documentation
doc-choices-incompatible-type	Documentation	Error	Choices value from the documentation is not compatible with type defined in the argument_spec
doc-default-does-not-match-spec	Documentation	Error	Value for “default” from the argument_spec does not match the documentation
doc-default-incompatible-type	Documentation	Error	Default value from the documentation is not compatible with type defined in the argument_spec
doc-elements-invalid	Documentation	Error	Documentation specifies elements for argument, when “type” is not `list`.
doc-elements-mismatch	Documentation	Error	Argument_spec defines elements different than documentation does
doc-missing-type	Documentation	Error	Documentation doesn’t specify a type but argument in `argument_spec` use default type (`str`)
doc-required-mismatch	Documentation	Error	argument in argument_spec is required but documentation says it is not, or vice versa
doc-type-does-not-match-spec	Documentation	Error	Argument_spec defines type different than documentation does
documentation-error	Documentation	Error	Unknown `DOCUMENTATION` error
documentation-syntax-error	Documentation	Error	Invalid `DOCUMENTATION` schema
import-before-documentation	Imports	Error	Import found before documentation variables. All imports must appear below `DOCUMENTATION`/`EXAMPLES`/`RETURN`
import-error	Documentation	Error	`Exception` attempting to import module for `argument_spec` introspection
attributes-check-mode	Documentation	Error	If a module documents the `check_mode` attribute, its `support` value must be compatible with the `supports_check_mode` parameter of `AnsibleModule`
attributes-check-mode-details	Documentation	Error	If a module documents the `check_mode` attribute with support values `partial` or `N/A`, it must provide `details`
import-placement	Locations	Warning	Imports should be directly below `DOCUMENTATION`/`EXAMPLES`/`RETURN`
imports-improper-location	Imports	Error	Imports should be directly below `DOCUMENTATION`/`EXAMPLES`/`RETURN`
incompatible-choices	Documentation	Error	Choices value from the argument_spec is not compatible with type defined in the argument_spec
incompatible-default-type	Documentation	Error	Default value from the argument_spec is not compatible with type defined in the argument_spec
invalid-argument-name	Documentation	Error	Argument in argument_spec must not be one of ‘message’, ‘syslog_facility’ as it is used internally by Ansible Core Engine
invalid-argument-spec	Documentation	Error	Argument in argument_spec must be a dictionary/hash when used
invalid-argument-spec-options	Documentation	Error	Suboptions in argument_spec are invalid
invalid-documentation	Documentation	Error	`DOCUMENTATION` is not valid YAML
invalid-documentation-markup	Documentation	Error	`DOCUMENTATION` or `RETURN` contains invalid markup
invalid-documentation-options	Documentation	Error	`DOCUMENTATION.options` must be a dictionary/hash when used
invalid-examples	Documentation	Error	`EXAMPLES` is not valid YAML
invalid-extension	Naming	Error	Official Ansible modules must have a `.py` extension for python modules or a `.ps1` for powershell modules
invalid-module-schema	Documentation	Error	`AnsibleModule` schema validation error
invalid-removal-version	Documentation	Error	The version at which a feature is supposed to be removed cannot be parsed (for collections, it must be a semantic version)
invalid-requires-extension	Naming	Error	Module `#AnsibleRequires -CSharpUtil` should not end in .cs, Module `#Requires` should not end in .psm1
missing-doc-fragment	Documentation	Error	`DOCUMENTATION` fragment missing
missing-existing-doc-fragment	Documentation	Warning	Pre-existing `DOCUMENTATION` fragment missing
missing-documentation	Documentation	Error	No `DOCUMENTATION` provided
missing-examples	Documentation	Error	No `EXAMPLES` provided
missing-gplv3-license	Documentation	Error	GPLv3 license header not found
missing-module-utils-basic-import	Imports	Warning	Did not find `ansible.module_utils.basic` import
missing-module-utils-import-csharp-requirements	Imports	Error	No `Ansible.ModuleUtils` or C# Ansible util requirements/imports found
missing-powershell-interpreter	Syntax	Error	Interpreter line is not `#!powershell`
missing-python-interpreter	Syntax	Error	Interpreter line is not `#!/usr/bin/python`
missing-return	Documentation	Error	No `RETURN` documentation provided
missing-return-legacy	Documentation	Warning	No `RETURN` documentation provided for legacy module
missing-suboption-docs	Documentation	Error	Argument in argument_spec has sub-options but documentation does not define sub-options
module-incorrect-version-added	Documentation	Error	Module level `version_added` is incorrect
module-invalid-version-added	Documentation	Error	Module level `version_added` is not a valid version number
module-utils-specific-import	Imports	Error	`module_utils` imports should import specific components, not `*`
multiple-utils-per-requires	Imports	Error	`Ansible.ModuleUtils` requirements do not support multiple modules per statement
multiple-csharp-utils-per-requires	Imports	Error	Ansible C# util requirements do not support multiple utils per statement
no-default-for-required-parameter	Documentation	Error	Option is marked as required but specifies a default. Arguments with a default should not be marked as required
no-log-needed	Parameters	Error	Option name suggests that the option contains a secret value, while `no_log` is not specified for this option in the argument spec. If this is a false positive, explicitly set `no_log=False`
nonexistent-parameter-documented	Documentation	Error	Argument is listed in DOCUMENTATION.options, but not accepted by the module
option-incorrect-version-added	Documentation	Error	`version_added` for new option is incorrect
option-invalid-version-added	Documentation	Error	`version_added` for option is not a valid version number
parameter-invalid	Documentation	Error	Argument in argument_spec is not a valid python identifier
parameter-invalid-elements	Documentation	Error	Value for “elements” is valid only when value of “type” is `list`
implied-parameter-type-mismatch	Documentation	Error	Argument_spec implies `type="str"` but documentation defines it as different data type
parameter-type-not-in-doc	Documentation	Error	Type value is defined in `argument_spec` but documentation doesn’t specify a type
parameter-alias-repeated	Parameters	Error	argument in argument_spec has at least one alias specified multiple times in aliases
parameter-alias-self	Parameters	Error	argument in argument_spec is specified as its own alias
parameter-documented-multiple-times	Documentation	Error	argument in argument_spec with aliases is documented multiple times
parameter-list-no-elements	Parameters	Error	argument in argument_spec “type” is specified as `list` without defining “elements”
parameter-state-invalid-choice	Parameters	Error	Argument `state` includes `get`, `list` or `info` as a choice. Functionality should be in an `_info` or (if further conditions apply) `_facts` module.
python-syntax-error	Syntax	Error	Python `SyntaxError` while parsing module
removal-version-must-be-major	Documentation	Error	According to the semantic versioning specification (https://semver.org/), the only versions in which features are allowed to be removed are major versions (x.0.0)
return-syntax-error	Documentation	Error	`RETURN` is not valid YAML, `RETURN` fragments missing or invalid
return-invalid-version-added	Documentation	Error	`version_added` for return value is not a valid version number
subdirectory-missing-init	Naming	Error	Ansible module subdirectories must contain an `__init__.py`
try-except-missing-has	Imports	Warning	Try/Except `HAS_` expression missing
undocumented-parameter	Documentation	Error	Argument is listed in the argument_spec, but not documented in the module
unidiomatic-typecheck	Syntax	Error	Type comparison using `type()` found. Use `isinstance()` instead
unknown-doc-fragment	Documentation	Warning	Unknown pre-existing `DOCUMENTATION` error
use-boto3	Imports	Error	`boto` import found, new modules should use `boto3`
use-fail-json-not-sys-exit	Imports	Error	`sys.exit()` call found. Should be `exit_json`/`fail_json`
use-module-utils-urls	Imports	Error	`requests` import found, should use `ansible.module_utils.urls` instead
use-run-command-not-os-call	Imports	Error	`os.call` used instead of `module.run_command`
use-run-command-not-popen	Imports	Error	`subprocess.Popen` used instead of `module.run_command`
use-short-gplv3-license	Documentation	Error	GPLv3 license header should be the short form for new modules
mutually_exclusive-type	Documentation	Error	mutually_exclusive entry contains non-string value
mutually_exclusive-collision	Documentation	Error	mutually_exclusive entry has repeated terms
mutually_exclusive-unknown	Documentation	Error	mutually_exclusive entry contains option which does not appear in argument_spec (potentially an alias of an option?)
required_one_of-type	Documentation	Error	required_one_of entry contains non-string value
required_one_of-collision	Documentation	Error	required_one_of entry has repeated terms
required_one_of-unknown	Documentation	Error	required_one_of entry contains option which does not appear in argument_spec (potentially an alias of an option?)
required_together-type	Documentation	Error	required_together entry contains non-string value
required_together-collision	Documentation	Error	required_together entry has repeated terms
required_together-unknown	Documentation	Error	required_together entry contains option which does not appear in argument_spec (potentially an alias of an option?)
required_if-is_one_of-type	Documentation	Error	required_if entry has a fourth value which is not a bool
required_if-requirements-type	Documentation	Error	required_if entry has a third value (requirements) which is not a list or tuple
required_if-requirements-collision	Documentation	Error	required_if entry has repeated terms in requirements
required_if-requirements-unknown	Documentation	Error	required_if entry’s requirements contains option which does not appear in argument_spec (potentially an alias of an option?)
required_if-unknown-key	Documentation	Error	required_if entry’s key does not appear in argument_spec (potentially an alias of an option?)
required_if-key-in-requirements	Documentation	Error	required_if entry contains its key in requirements list/tuple
required_if-value-type	Documentation	Error	required_if entry’s value is not of the type specified for its key
required_by-collision	Documentation	Error	required_by entry has repeated terms
required_by-unknown	Documentation	Error	required_by entry contains option which does not appear in argument_spec (potentially an alias of an option?)
version-added-must-be-major-or-minor	Documentation	Error	According to the semantic versioning specification (https://semver.org/), the only versions in which features are allowed to be added are major and minor versions (x.y.0)