Fix "vault password file not found" Error in Ansible Vault

The Error

You're running a playbook with vault-encrypted variables and suddenly:

ERROR! The vault password file /path/to/.vault_pass was not found or is not readable

This one hits me most often after cloning a repo onto a new machine, wiring up CI/CD, or just running the playbook from the wrong directory. The playbook worked fine yesterday. Now it doesn't. Here's how I debug it.

Debug Process

1. Find out where Ansible is looking for the vault password file

The path could be coming from three different places. Check them in this order:

• ansible.cfg in the current directory or your home directory
• The ANSIBLE_VAULT_PASSWORD_FILE environment variable
• The --vault-password-file CLI flag

# Check your ansible.cfg
grep -r vault_password_file ansible.cfg ~/.ansible.cfg /etc/ansible/ansible.cfg 2>/dev/null

# Check environment variable
echo $ANSIBLE_VAULT_PASSWORD_FILE

2. Verify the file actually exists at that path

ls -la /path/to/.vault_pass

No such file or directory means it's genuinely missing — never created on this machine, deleted, or the path is just wrong.

File exists but the error persists? That's a permissions problem:

stat /path/to/.vault_pass
# Look at the "Access" line — needs to be readable by the user running ansible

3. Check if it's a relative path problem

Here's a classic gotcha. When ansible.cfg has a relative path like vault_password_file = .vault_pass, Ansible resolves it against the current working directory — not the location of the config file itself. Run the playbook from a different directory, and it breaks.

# Breaks — running from the parent directory
cd /home/user
ansible-playbook myproject/site.yml

# Works — run from the project root where .vault_pass lives
cd /home/user/myproject
ansible-playbook site.yml

Solutions

Solution 1: Create the missing vault password file

On a fresh machine or a freshly cloned repo, the file simply won't exist yet. You need to recreate it. A vault password file is just plain text — one line, the password, nothing else.

# Create the file
echo 'your_vault_password_here' > ~/.vault_pass

# Lock it down — only the owner should read this
chmod 600 ~/.vault_pass

The password must match what was used to encrypt the vault originally. Forgotten it? The data is unrecoverable. That's vault working as intended.

Solution 2: Fix permissions

The file exists, but Ansible still can't read it:

# Fix ownership and permissions
chown $USER ~/.vault_pass
chmod 600 ~/.vault_pass

# Verify
ls -la ~/.vault_pass
# Should show: -rw------- 1 youruser yourgroup ...

Solution 3: Use an absolute path in ansible.cfg

Switching to an absolute path cuts the "which directory am I in" problem entirely:

[defaults]
vault_password_file = /home/youruser/.vault_pass

Tilde works too — Ansible expands it correctly:

[defaults]
vault_password_file = ~/.vault_pass

Solution 4: Pass it on the command line

Need to run right now without touching config? Use the flag:

ansible-playbook site.yml --vault-password-file ~/.vault_pass

# Or type the password interactively
ansible-playbook site.yml --ask-vault-pass

Solution 5: Use an environment variable (for CI/CD)

Automated pipelines shouldn't have password files checked in. Store the vault password as a CI secret and write it to a temp file at runtime — then delete it when done:

# GitHub Actions example
- name: Run playbook
  env:
    VAULT_PASS: ${{ secrets.ANSIBLE_VAULT_PASSWORD }}
  run: |
    echo "$VAULT_PASS" > /tmp/.vault_pass
    chmod 600 /tmp/.vault_pass
    ansible-playbook site.yml --vault-password-file /tmp/.vault_pass
    rm -f /tmp/.vault_pass

Solution 6: Use a vault password script

More complex setups — multiple vault IDs, pulling from AWS Secrets Manager or HashiCorp Vault — can use an executable script instead of a plain file. Ansible runs it and reads the password from stdout:

#!/bin/bash
# get-vault-pass.sh
echo "$VAULT_PASSWORD"

chmod +x get-vault-pass.sh

# ansible.cfg
[defaults]
vault_password_file = ./get-vault-pass.sh

Verification

Before running the full playbook, confirm the fix works with a quick decrypt test:

# Try viewing an encrypted file directly
ansible-vault view group_vars/all/vault.yml

# Or decrypt to stdout without writing a file
ansible-vault decrypt --output - group_vars/all/vault.yml

Decrypted content on screen? You're done. Getting ERROR! Decryption failed instead? The file is found and readable — but the password is wrong.

Tips

• Add .vault_pass and similar patterns to .gitignore immediately. Never commit vault password files.
• Keep chmod 600 on the file. Some Ansible versions refuse to use world-readable password files, and beyond that, it's just poor practice.
• Need a strong random vault password? ToolCraft's password generator runs entirely in the browser — nothing hits a server — and produces cryptographically random output. Good enough for vault secrets.
• In your project README, document which vault ID maps to which password file. Not the password — just the mapping. Future teammates (including future you, six months from now) will thank you.

Lessons Learned

Almost every vault password file not found error comes down to three root causes: the file doesn't exist on this machine yet, the path in ansible.cfg is relative and you're in the wrong directory, or the permissions are off.

The permanent fix is simple: use an absolute path (or ~/.vault_pass) in ansible.cfg, keep the file at chmod 600, and store the vault password somewhere secure like a password manager. For team projects, pick one standard location — ~/.vault_pass works fine — and put it in the README so the next person setting up the project knows exactly what to create.