Troubleshooting

Troubleshooting

Common Errors

1. Cannot Connect to NPM API

Error:

fatal: [localhost]: FAILED! => {"msg": "ConnectionError: HTTPConnectionPool(host='...'): Max retries exceeded"}

Causes & Fixes:

Cause	Fix
NPM container is not running	docker compose -f docker/docker-compose_npm.yml up -d
Wrong npm_host or npm_port	Check defaults/main.yml → npm_host, npm_port
Firewall blocks port 81	sudo ufw allow 81/tcp or check iptables
NPM still initializing	Wait 15-30 seconds after container start

Quick test:

curl -s http://localhost:81/api/ | python -m json.tool

---

2. Authentication Failed (401)

Error:

FAILED! => {"msg": "Failed to get token: 401"}

Causes & Fixes:

• Wrong credentials — verify npm_admin_user and npm_admin_pass match NPM settings
• First run defaults — NPM default credentials are admin@example.com / changeme
• Token expired — tokens are obtained fresh each playbook run, but if the admin password was changed manually, update the vault

Verify credentials:

curl -s -X POST http://localhost:81/api/tokens \
  -H 'Content-Type: application/json' \
  -d '{"identity":"admin@example.com","secret":"changeme"}'

---

3. Proxy Host Already Exists

Behavior: The module skips creation with changed: false and returns existing host data.

This is expected — the module is idempotent. If a host with matching domain_names already exists, it is not recreated.

---

4. SSL Certificate Errors

Error:

FAILED! => {"msg": "Certificate creation failed"}

Checks:

1. DNS for the domain must resolve to the NPM server's public IP
2. Port 80 must be open (Let's Encrypt HTTP-01 challenge)
3. The letsencrypt_agree must be true
4. Check NPM container logs: docker logs npm-app

---

5. Docker Compose Issues

Error:

Error: service "app" depends on undefined service

Fix: Ensure you're using the correct compose file:

docker compose -f docker/docker-compose_npm.yml up -d

Container won't start:

# Check logs
docker compose -f docker/docker-compose_npm.yml logs -f

# Recreate containers
docker compose -f docker/docker-compose_npm.yml down
docker compose -f docker/docker-compose_npm.yml up -d

---

6. Ansible Vault Errors

Error:

ERROR! Attempting to decrypt but no vault secrets found

Fix: Run with --ask-vault-pass or set vault password file:

# Interactive
ansible-playbook playbook.yml --ask-vault-pass

# Password file
ansible-playbook playbook.yml --vault-password-file ~/.vault_pass

Can't decrypt api_secret.yml:

# Re-encrypt with new password
ansible-vault rekey roles/npm-management/vars/api_secret.yml

---

7. Module Import Errors

Error:

ModuleNotFoundError: No module named 'requests'

Fix:

pip install requests

The requests library must be installed on the control node (where Ansible runs), not on the target host.

---

Debugging Tips

Enable Ansible Verbose Output

# Increase verbosity
ansible-playbook playbook.yml -vvv

Debug Module Directly

# Run the module standalone (for testing)
python library/npm_proxy.py /tmp/args.json

Where /tmp/args.json contains:

{
    "ANSIBLE_MODULE_ARGS": {
        "npm_host": "localhost",
        "npm_port": 81,
        "action": "search_proxy_host",
        "admin_user": "admin@example.com",
        "admin_pass": "changeme",
        "domain_names": ["example.com"]
    }
}

Check NPM API Directly

# Get token
TOKEN=$(curl -s -X POST http://localhost:81/api/tokens \
  -H 'Content-Type: application/json' \
  -d '{"identity":"admin@example.com","secret":"changeme"}' | python -c "import sys,json; print(json.load(sys.stdin)['token'])")

# List all proxy hosts
curl -s http://localhost:81/api/nginx/proxy-hosts \
  -H "Authorization: Bearer $TOKEN" | python -m json.tool

# Get specific host
curl -s http://localhost:81/api/nginx/proxy-hosts/1 \
  -H "Authorization: Bearer $TOKEN" | python -m json.tool

View Container Logs

# Follow logs in real time
docker logs -f npm-app

# Last 50 lines
docker logs --tail 50 npm-app

---

Getting Help

1. Check GitHub Issues
2. Review NPM documentation
3. Check NPM API docs — the API is not officially documented, use browser DevTools against the NPM UI to discover endpoints