Troubleshooting
The usual problems and how to solve them. Missing yours? Open an issue.
Signing in
I lost the setup code
Run docker logs d2ha. Until the account exists, every start prints a new code: if the log is gone, restart the container and read the new one.
I forgot the password
There is no reset link. To start again, stop D2HA, delete data/d2ha.json and start it: it prints a new setup code. This also deletes the API token, the settings, the Telegram choices and which containers Home Assistant sees, so create a new token for Home Assistant afterwards.
The two-factor code is refused
The codes depend on the time: check that the clock of your phone is right. The same applies to the server.
Too many attempts
After 5 wrong attempts from one address in 15 minutes (or 30 from anywhere), sign-in is blocked. Wait a few minutes.
Updates
A container shows “Check failed”
The registry did not answer or refused; hover the badge for the reason. For a private registry, run docker login on the host: D2HA then asks through Docker, which needs DISTRIBUTION: 1 on the socket proxy. The next check tries again.
I use an exact version and D2HA never finds updates
D2HA follows the tag you run. For 1.2.3 it only notices a rebuild of 1.2.3; change the tag yourself to move on, or run a tag that moves, such as latest or 1.
No release notes
The image must say its version and its GitHub repository in its labels, and the repository must have a release with that version (see Release notes). With many containers, GitHub's limit of 60 requests per hour runs out: add D2HA_GITHUB_TOKEN.
The version shows a tag and a short digest
The image does not say its version in a label, so D2HA shows what it has: the tag and the start of the digest. When both sides show the same version with different digests, the label came from the base image.
“The new container did not start: the previous one has been restored”
Docker could not create or start the new container (a port already taken, a missing volume…). The old one runs again. The message shows Docker's reason; the container logs may say more.
“Download of the image failed”
The registry refused or the disk is full. Nothing was changed. Clean images frees space taken by images no container uses.
There is no Update button for D2HA or the proxy
On purpose: D2HA would lose itself, or its Docker access, halfway. Update both with docker compose pull and docker compose up -d (Updating D2HA).
Home Assistant
“Cannot reach D2HA at this address”
The address is the one Home Assistant sees. 127.0.0.1 works only when Home Assistant runs on the same host with the host network; see The address. Check that D2HA runs: docker ps. If D2HA moved (a new host, a reverse proxy, a different port), change the address with Reconfigure: see Change the address.
“The token is wrong or was revoked”
Create a new token in D2HA, Settings → Home Assistant, and paste it in Home Assistant.
Entities are unavailable
All of them: D2HA is down or unreachable. Only some: those containers were hidden in D2HA or removed; delete their devices (Choose the containers).
A bug report for the integration
Attach the diagnostics: Settings → Devices & services → D2HA → ⋮ → Download diagnostics. The address and the token are blacked out in the file (see Diagnostics).
Telegram
No message at all
Check Settings → Telegram notifications: if it says Not configured, the token or the chat id is missing. Then press Send a test message: the error says what Telegram did not like. Send your bot a message first, or it cannot write to you.
Update messages arrive, crash alerts do not
Those come from the Docker events: keep EVENTS: 1 on the socket proxy. A container with d2ha.notify=false is left out on purpose, and stops you asked for never send one.
The web app
D2HA does not install as an app
Browsers install apps only from HTTPS. Behind an access layer, let /sw.js and /static/ through without sign-in.
The page inside Home Assistant stays blank
Add the address of Home Assistant to D2HA_FRAME_ANCESTORS, and use addresses on the same site (D2HA inside a dashboard).
Something wrong or missing on this page? Open an issue.