🚨 Ansible Error: 'None of the provided paths were usable. Please specify a valid path with --roles-path' — Cause, Fix, and Troubleshooting Guide

Overview

When ansible-galaxy role install cannot write to any of the roles paths it knows about — because none exist, none are writable, or the configured path is wrong — it refuses to install and tells you to specify one:

ERROR! None of the provided paths were usable. Please specify a valid path with --roles-path

This is a control-node filesystem/permissions issue during dependency installation.

Symptoms

• ansible-galaxy install -r requirements.yml fails without installing anything.
• Happens in CI containers where the default ~/.ansible/roles is not writable.
• Works locally (writable home) but fails in an automated build.

ansible-galaxy install -r requirements.yml

ERROR! None of the provided paths were usable. Please specify a valid path with --roles-path

Common Root Causes

1. Default roles path does not exist or is not writable

~/.ansible/roles and /etc/ansible/roles may be absent or root-owned in a container running as a non-root user.

2. roles_path in ansible.cfg points somewhere invalid

A configured path that was never created, or a relative path from the wrong working directory.

3. Read-only or ephemeral home in CI

The build user has no writable $HOME, so the default path fails.

How to diagnose

Show the configured roles paths:

ansible-config dump | grep -i roles_path

Check writability of the candidate paths:

ls -ld ~/.ansible/roles /etc/ansible/roles 2>/dev/null
touch ~/.ansible/roles/.wtest 2>&1 || echo "not writable"

Fixes

Point installs at a project-local, writable path

mkdir -p ./roles
ansible-galaxy install -r requirements.yml --roles-path ./roles

Set roles_path in ansible.cfg (persistent)

# ansible.cfg
[defaults]
roles_path = ./roles:~/.ansible/roles

Use an environment variable in CI

export ANSIBLE_ROLES_PATH="$PWD/roles"
mkdir -p "$ANSIBLE_ROLES_PATH"
ansible-galaxy install -r requirements.yml

Fix ownership if a path is root-owned

sudo chown -R "$(id -u):$(id -g)" ~/.ansible

Verify:

ansible-galaxy role list

What to watch out for

• Keep roles in a project-local roles/ directory and commit requirements.yml so every environment installs to a predictable, writable location.
• In CI, set ANSIBLE_ROLES_PATH (and ANSIBLE_COLLECTIONS_PATH) explicitly rather than relying on $HOME.
• A colon-separated roles_path is searched in order; the first writable one is used for installs.

Related

• Ansible Error: ‘The role was not found’
• Ansible Error: Galaxy certificate verify failed
• Managing Ansible Galaxy Dependencies and Requirements With AI