Troubleshooting and FAQ

Start with the history page in the panel: every update attempt is there with its result, and most problems below are diagnosed from the reason it shows.

My hostname is not updating

Work down this list:

1. Is the updater running? Check the router's DynDNS page or the device's cron. A rebooted Pi or a router that lost its settings in a firmware update stops silently.
2. What does history say? Rows appearing means the updater reaches us; the reason column says the rest. No rows means requests are not arriving: wrong server (legitdns.com), no route out, or the client not running.
3. Is it just cache? DNS answers are cached for up to about five minutes (the TTL). If history shows a good update, wait, then check with dig +short your-hostname again.
4. Is the hostname offline? An offline hostname accepts and records updates but publishes nothing (the reason shows offline_held). Switch it back online on its panel page.
5. One updater only. Two devices updating one hostname with different addresses overwrite each other.

The address is right but I cannot connect

History shows good updates and dig shows the address you expect, but connections to the device time out. DNS has done its part; something between the internet and the device is stopping the connection: no port forward on the router, the device's own firewall, or a shared provider address (CGNAT), where connections from outside cannot reach you at all. Reaching your device from outside has the tests - starting with comparing your router's WAN address against /checkip - and what to do about each.

Answer codes and what to do

badauth

The token did not check out. In order of likelihood:

• The client's token is not the one the panel most recently showed. Regenerating kills the old one - re-copy the current token.
• Username/password swapped or trimmed - the username is the full hostname, the password is the token.
• The token expired (maximum age), or the update comes from outside its allowed sources. Your history page shows which rule fired; the refusal itself never says, on purpose.
• A stale config somewhere (the retired router in the cupboard) is spraying attempts. Repeated wrong attempts are answered ever more slowly and count toward the rate limits - find and unplug it.

nohost

No hostname by that name - check the spelling, domain part included. In multi-hostname DynDNS2 requests, it means your username's hostname was not among them; see the multi-hostname rule.

notfqdn

The hostname is not a full domain name. Send the whole name (mypi.pihome.example), not just the label.

badagent

No User-Agent header, or the request was not a GET. Routers and clients always send one; hand-written requests must add it (curl: -A "myclient/1.0").

abuse

Rate limited: over 300 attempts in an hour from your address, or over 120 authenticated updates in an hour on the account. Stop the client, wait out the hour, then fix why it retried so hard - updates should be rare events.

911 (DynDNS2) / zone_error (API)

A problem on our side while publishing; your client did nothing wrong. Wait a few minutes and retry - back off instead of looping.

badrequest (DynDNS2) / invalid_ip (API)

The address sent is not usable: not an IP address, or an IPv4 address in the IPv6 field. Private and loopback addresses are refused - they can never work from the internet. Check what your checkip source returns - an updater publishing the text of an error page hits this. Our /checkip returns a bare address and nothing else.

offline_held and redirect_held

Not an error: the API answers with these reasons but still returns 200. The update was authenticated and recorded, addresses saved as last-known, but the hostname is offline or in redirect mode, so nothing was published. Switch the mode on its panel page to make it live again.

IPv6 notes

• ddclient users: 3.10.0's modern usev6 cannot publish IPv6 (a ddclient bug - it sends an empty address). Use the legacy use=ip form, as the ddclient guide shows, or inadyn or our script for IPv6.
• inadyn users: your config must set allow-ipv6 = true, or inadyn refuses its own IPv6 result. The inadyn guide includes the line.
• Publishing the wrong family: if your connection has no IPv6, an updater cannot invent one. Sending nothing for a family leaves that record alone; nothing is cleared by accident.
• Which IPv6? A device may have several - a stable one and rotating temporary privacy addresses. Publish the stable one. /checkip reports the address a connection from the device actually uses, which in most home setups is the one that accepts connections back.

FAQ

My IP changed but the hostname still points at the old address

Probably cache (up to five minutes), or the updater has not noticed. History page: a recent ok row means we hold the new address and the rest is propagation. No row means no update was sent.

Can I update two hostnames from one device?

Yes - run one config per hostname, each with its own token. Our scripts take one config file each; run the script once per config.

Can two devices share one hostname?

Technically yes, practically no - they will overwrite each other whenever their addresses differ. Give each device its own hostname.

I lost my token

Generate a new one on the hostname's panel page. The old one stops working at once; update the device config with the new one.

What happens if I stop using the service?

If your account has no activity for six months - no sign-in, no updates - we send warning emails first (a month before, then a week before), then close the account and free its hostnames for others to register. Signing in, or keeping a hostname updated, counts as activity and restarts the clock.

Why did my update work in the panel but the device still fails?

The panel update normally works off your sign-in, not the token - the token box on the form is optional, and empty means "use my sign-in". So a working panel update shows the hostname and the service are fine, but it says nothing about the token unless you pasted the token in. The device's stored token or username is the suspect. Compare them character by character; trailing spaces in config files are a classic.

Do you support client X or router Y?

Only what we have tested ourselves is called supported: the client guides. The router guides are "should work" - the maker's manual documents a custom update URL; we have not tested those models yet.