🚨 Ansible Error: 'Could not find or access ... on the Ansible Controller' — Cause, Fix, and Troubleshooting Guide

Overview

Modules that ship a file from the control node to the target — copy, template, unarchive, and the file/lookup plugins — first resolve the source on the controller. When that source path does not exist or is not readable, the task fails before anything is sent:

fatal: [web-01]: FAILED! => {"changed": false, "msg": "Could not find or access 'nginx.conf.j2' on the Ansible Controller.\nIf you are using a module and expect the file to exist on the remote, see the remote_src option"}

The key phrase is on the Ansible Controller — Ansible is looking for the file locally where the playbook runs, not on the managed host.

Symptoms

• copy/template fails immediately with a source path in the message.
• The path looks correct to you but Ansible cannot find it.
• The file exists on the target host, and you expected Ansible to use it there.

ansible-playbook -i inventory.ini site.yml

TASK [web : deploy vhost] ******
fatal: [web-01]: FAILED! => {"msg": "Could not find or access 'templates/vhost.conf.j2' on the Ansible Controller."}

Common Root Causes

1. Wrong relative path

src is relative to the playbook (or the role’s files//templates/ dir), not your shell’s current directory. A path that works in ls may not resolve during the play.

2. Role search paths not used

Inside a role, copy: src=app.conf searches the role’s files/ directory automatically. If the file is elsewhere (or you are not in a role), the shortcut fails.

3. The file genuinely does not exist / typo

A rename, a missing git add, or a wrong extension (.j2 vs .conf).

4. You meant a file on the remote host

You want to copy a file that already lives on the target — that requires remote_src: true, otherwise Ansible looks on the controller.

How to diagnose

Confirm where Ansible thinks it is running and what the source resolves to:

ansible-playbook -i inventory.ini site.yml -vvv 2>&1 | grep -i "could not find"

Check the file exists on the controller relative to the playbook/role:

ls -l templates/vhost.conf.j2 roles/web/templates/vhost.conf.j2 2>/dev/null

Fixes

Put the file where the module searches

For a role, drop templates in roles/<role>/templates/ and files in roles/<role>/files/, then reference the bare name:

- name: Deploy vhost
  ansible.builtin.template:
    src: vhost.conf.j2          # resolves to roles/web/templates/vhost.conf.j2
    dest: /etc/nginx/conf.d/site.conf

Use an explicit, correct relative path

- name: Copy app config
  ansible.builtin.copy:
    src: files/app.conf          # relative to the playbook directory
    dest: /etc/app/app.conf

If the source is already on the target, use remote_src

- name: Copy an existing remote file
  ansible.builtin.copy:
    src: /opt/app/app.conf.sample
    dest: /etc/app/app.conf
    remote_src: true             # look on the managed host, not the controller

Verify the file is committed and present

git status --short roles/web/templates/

What to watch out for

• role_path/collection layout matters: copy and template search files//templates/ respectively; other modules do not get that shortcut.
• Symlinks pointing outside the role can break when Ansible copies the tree; use real files.
• A missing file in CI but present locally usually means it was never committed — check git status before blaming Ansible.

Related

• Ansible Error: ‘Destination directory does not exist’
• Ansible Error: template error while templating string
• Ansible Error: ‘The role was not found’