ansible-lint "syntax-check[specific]" failure in CI

By Kaveh Alemi·Latchkey

ansible-lint first runs an Ansible syntax check on each playbook. If that fails (a bad module argument, an unresolvable collection, an unparseable structure), it reports syntax-check[specific], an internal-error rule that halts linting and cannot be disabled.

What this error means

ansible-lint fails with "syntax-check[specific]" and the underlying Ansible error, such as an unknown module or a missing collection, and no other rules are evaluated.

syntax-check[specific]: couldn't resolve module/action 'community.docker.docker_container'.
This often indicates a misspelling, missing collection, or incorrect module path.
playbooks/deploy.yml:12:7

Common causes

A collection used by the playbook is not installed

The syntax check cannot resolve a module whose collection was not installed in the lint environment, so it errors before rule evaluation.

A genuine syntax or argument error

A malformed task, an invalid module argument, or a YAML structure Ansible cannot parse triggers the syntax check failure.

How to fix it

Install collections before linting

1. Install the collections your playbooks use from requirements.yml.
2. Re-run ansible-lint so the syntax check can resolve modules.

ansible-galaxy collection install -r requirements.yml
ansible-lint

Fix the underlying Ansible error

Run the syntax check directly to see the raw Ansible message and correct the module name or argument.

ansible-playbook --syntax-check playbooks/deploy.yml

How to prevent it

• Install collection dependencies in the lint job.
• Keep requirements.yml current with the modules you use.
• Run a local syntax check before pushing.

Frequently asked questions

Related guides

References

• Terraform documentation
• GitHub Actions documentation