# Ansible Errors
Common Ansible playbook failures and fixes.
## Task Failures
### "failed: UNREACHABLE!"
**Problem:** Cannot connect to VPS via SSH.
**Solution:** See [SSH Problems](troubleshooting/ssh-problems.md)
### "failed: [host] => Permission denied"
**Problem:** Insufficient sudo privileges.
**Solutions:**
```bash
# Verify ansible user has passwordless sudo
ssh ansible@vps "sudo -n true"
# Re-bootstrap if needed
auberge ansible bootstrap my-vps --ip 203.0.113.10
```
### "apt lock" errors
**Problem:** Another apt process running.
**Solutions:**
```bash
# Wait a minute and retry
# Or kill apt processes (via provider console)
sudo killall apt apt-get
sudo rm /var/lib/apt/lists/lock
sudo rm /var/cache/apt/archives/lock
sudo rm /var/lib/dpkg/lock*
```
### "Package not found"
**Problem:** Package unavailable in apt sources.
**Solutions:**
```bash
# Update apt cache
ssh ansible@vps "sudo apt update"
# Check package name
ssh ansible@vps "apt-cache search package-name"
```
## Systemd Failures
### "Service failed to start"
**Check logs:**
```bash
ssh ansible@vps "journalctl -u service-name -n 50"
```
**Common causes:**
- Config file syntax error
- Port already in use
- Missing dependencies
- File permissions
**Solutions:**
```bash
# Validate config
# Check port availability
# Fix permissions
auberge ansible run --host vps --tags service-name
```
### "Unit not found"
**Problem:** Systemd service file doesn't exist.
**Solution:**
```bash
# Re-run ansible to create service
auberge ansible run --host vps --tags service-name
```
## Templating Errors
### "Undefined variable"
**Problem:** Required variable not set.
**Solution:**
```bash
# Check config
auberge config list
# Set if missing
auberge config set KEY value
```
### "template error"
**Problem:** Jinja2 template syntax error.
**Solution:**
- Check template in `ansible/roles/{role}/templates/`
- Verify variable names
- Test template syntax
## File/Directory Issues
### "No such file or directory"
**Problem:** Path doesn't exist.
**Solutions:**
```bash
# Let ansible create it
# Check tasks create parent directories first
# Or create manually
ssh ansible@vps "sudo mkdir -p /path/to/dir"
```
### "File exists"
**Problem:** File creation when file exists.
**Solution:**
- Use `state: present` instead of `state: touch`
- Or use `force: yes` to overwrite
## Network Issues
### "Connection timeout" downloading files
**Problem:** Slow or failed downloads.
**Solutions:**
```bash
# Retry ansible (idempotent)
auberge ansible run --host vps --tags role-name
# Check VPS network
ssh ansible@vps "ping -c 3 8.8.8.8"
# Download manually and scp to VPS if needed
```
### "SSL certificate verify failed"
**Problem:** Certificate validation failed.
**Solutions:**
```bash
# Update CA certificates
ssh ansible@vps "sudo apt update && sudo apt install -y ca-certificates"
# Or bypass validation (not recommended)
# Add to task: validate_certs: no
```
## Handler Issues
### Handler not running
**Problem:** Expected service restart didn't happen.
**Causes:**
- Task didn't report "changed"
- Handler syntax error
- Wrong handler name in notify
**Debug:**
```bash
# Check if task was marked as "changed"
# Manually restart
ssh ansible@vps "sudo systemctl restart service-name"
```
## Idempotency Issues
### Task always shows "changed"
**Problem:** Task not idempotent.
**Common culprits:**
- Using `command` or `shell` modules
- Not using `creates` or `removes` parameters
- File permissions changing unnecessarily
**Solutions:**
```bash
# Use appropriate module (file, package, service)
# Add changed_when: false for read-only commands
```
## Debug Techniques
### Verbose output
```bash
# Level 1
auberge ansible run --host vps -v
# Level 2 (detailed)
auberge ansible run --host vps -vv
# Level 3 (very detailed)
auberge ansible run --host vps -vvv
```
### Check mode
```bash
# Dry run to see what would change
auberge deploy --all --check --host vps
```
### Run specific task
```bash
# Use tags to isolate
auberge ansible run --host vps --tags specific-tag
```
### Manual execution
```bash
# Run ansible-playbook directly
cd ansible
ansible-playbook -i inventory.yml playbooks/apps.yml -vvv
```
## Recovery
### Playbook partially applied
**Problem:** Playbook stopped mid-execution.
**Solution:**
```bash
# Re-run (idempotent)
auberge ansible run --host vps --playbook playbooks/apps.yml
# Ansible skips successful tasks
# Reruns failed tasks
```
### System in inconsistent state
**Solutions:**
```bash
# Re-run full stack
auberge deploy --all --host vps
# Or restore from backup
auberge backup restore latest --host vps
```
## Related Pages
- [Running Playbooks](deployment/running-playbooks.md)
- [SSH Problems](troubleshooting/ssh-problems.md)
- [Common Issues](troubleshooting/common-issues.md)
- [Playbooks](core-concepts/playbooks.md)