DuckDNS & NGINX in Home Assistant: FAQ Troubleshooting Guide

27 Jul

⚠️ Before You Read the FAQs

Please make sure you’ve carefully followed all the setup steps from my guide, and rule out any possible human errors (such as typos, missed configuration lines, or skipped steps). These are the most common causes of issues — even for experienced users!

❗Scenario 1

Problem: DuckDNS URL not working when I’m on the internal network — what’s wrong?

Cause / Fix: Your router might have NAT loopback disabled, or it may not support it at all. This prevents you from accessing your external DuckDNS URL (https://yourname.duckdns.org) while connected to your home network. You can work around this by using your local IP (e.g. http://192.168.x.x:8123) when connected to your home network."

❗ Scenario 2

Problem: I can access Home Assistant via local IP on my internal network, but can’t access the external DuckDNS URL from either inside or outside my home.

Cause / Fix: Your internet provider may be using CGNAT (Carrier-Grade NAT), which prevents port forwarding from working. This means external requests to your DuckDNS address never reach your home network.

→ Contact your ISP and ask if you're behind CGNAT. If so, request a public IP address (dynamic or static). Some providers will disable CGNAT on request, often for free.

❗ Scenario 3

Problem: I can’t access Home Assistant via the local IP or DuckDNS URL — from either inside or outside my network.

Cause / Fix: This often happens if you’ve enabled SSL in configuration.yaml while also using the NGINX SSL proxy add-on — causing a conflict. Home Assistant begins expecting HTTPS directly, but NGINX is already handling the SSL externally.

Check your configuration.yaml under the http: section:

http:
# ssl_certificate: /ssl/fullchain.pem
# ssl_key: /ssl/privkey.pem

→ If those lines are present, comment them out (add a #), then restart Home Assistant.

These SSL lines must be disabled when using NGINX, since it handles HTTPS on its own.

Accessing your configuration file:

Use Samba or SSH to edit configuration.yaml, if you already have those add-ons enabled.
If you can't access Home Assistant at all and have no file access, you may need to restore from a backup or use a hypervisor console (e.g. Proxmox).

❗ DuckDNS Errors from the Logs

Problem:
ERROR: deploy_challenge hook returned with non-zero exit code

Cause / Fix:
This usually means your DuckDNS token is incorrect — or it was pasted with an extra space at the beginning or end.
→ Double-check that your token matches exactly, with no leading/trailing spaces, and re-save the configuration.