Troubleshooting

Troubleshooting

Common issues and how to resolve them.

"Session open refused by peer"

Cause: Too many simultaneous SSH channels. Docker Compose tries to run container operations in parallel, and each opens multiple SSH channels. The NAS's sshd MaxSessions=10 gets exceeded.

Fix: The workflow sets COMPOSE_PARALLEL_LIMIT=3. If you're seeing this again (e.g. after adding many services to a single stack), either:

• Reduce the limit further
• Or increase MaxSessions in the NAS's /etc/ssh/sshd_config

Stack Deploy Fails but Others Succeed

The deployment loop continues past failures — one broken stack won't block others. Check:

1. The GitHub Actions log — expand the failing stack's group
2. Common causes:
   • Image pull failure — is the image name/tag correct? Is Docker Hub rate-limiting?
   • Port conflict — is another container already using that port?
   • Volume mount error — does the host path exist?
   • Network doesn't exist — external networks must be created first

Containers Start but Aren't Accessible

1. Check Traefik labels — is traefik.enable=true set? Is the rule correct?
2. Check DNS — does myapp.${DOMAIN} resolve to your Cloudflare-proxied IP?
3. Check network — is the container on the right Docker network?
4. Check Cloudflare-Companion — is it creating the DNS record automatically?

Token Replacement Not Working

If containers start but have literal #{TOKEN}# values in their config:

1. Verify the secret exists in KeyVault: az keyvault secret list --vault-name <name>
2. Check the naming convention — my-secret in KeyVault becomes MY_SECRET as an env var
3. Ensure the .env file uses the correct token format: #{MY_SECRET}# (with the #{}# wrapper)

WireGuard Connection Fails

See Network & Connectivity — Troubleshooting in the nas-as-code wiki.

Common causes:

• Home internet IP changed (update WireGuard endpoint or dynamic DNS)
• Router/firewall dropped the WireGuard port forward
• WireGuard peer config secret is stale

SSH Connection Refused

• Host key mismatch — NAS was rebuilt or SSH keys regenerated. Update HOST_FINGERPRINT secret.
• Key authentication failed — wrong SSH key. Verify SSH_PRIVATE_KEY matches what's in the NAS's authorized_keys.
• Timeout — WireGuard tunnel may not be up. Check the WireGuard step logs.

Azure KeyVault Access Denied

• SPN credentials expired — Azure SPN secrets have a default 1-year lifetime. Regenerate and update AZURE_SPN_CREDENTIALS in GitHub.
• RBAC removed — verify the SPN still has Key Vault Secrets User on the vault.

Container Keeps Restarting (CrashLoop)

1. Check logs: via Portainer or Dozzle
2. Common causes:
   • Missing environment variable (secret not injected properly)
   • Corrupt config directory (restore from backup or delete and let container recreate)
   • Image version incompatibility (pin to a specific tag instead of latest)