Skip to content

Troubleshooting

General

Things that need to work:

  • Docker API access to list and inspect containers
  • MQTT Publication of results
  • Home Assistant discovering the Update entities on MQTT
  • Home Assistant generating update notices in UI when there’s a new version
  • Command Topic message sent by Home Assistant when Update button clicked
  • Docker Compose available from shell to make updates and restart
  • Git command available in shell to check for local repo updates and pull

Updates2MQTT Logs

If running under docker, and following the container naming guidance, then see the logs using:

docker logs updates2mqtt

or change to the directory where the docker-compose.yaml is installed and do docker compose logs

Changing Log Level

Update the config.yaml and change the log level to DEBUG, which will show much more diagnostic information.

conf/config.yaml
log:
  level: DEBUG

When you have everything working, its best to change the log level back, so your container isn’t generating big logs.

Going Inside Container

From the docker-compose.yaml directory, execute

docker compose exec -it updates2mqtt bash

(if you have an old Docker install, you may need to use docker-compose instead of docker compose)

This will give you shell access inside the container, which is a good way of checking for path issues, permissio issues etc. For example, if you have compose directories in the /containers directory, you could cd /containers and validate that Updates2MQTT can see the other compose directories, ls the contents, and run docker compose or git actions there.

MQTT

If the host, port, user and password for MQTT are incorrect then usually this will show in the logs, or use a MQTT client to verify that Updates2MQTT is successfully posting to topics ( and that HomeAssistant itself is publishing to the same broker OK).

Updates2MQTT uses the Eclipse Paho Python Client for all MQTT interaction, using v2 of the callback API, and supports the older MQTT implementations as well as the newer v5 protocol. The Issues list might give you some clues for your situation.

MQTT Clients

Use a desktop MQTT app - MQTTX will let you subscribe to # and see everything on a broker, while MQTT Explorer automatically shows a tree structure of topics, and can run either as a desktop app, or as web app running on Docker.

These tools will let you inspect messages, and also publish your own, so can create your own update message and see if it gets picked up by the Home Assistant app.

Alternatively, use the debug option and logging of Mosquitto broker, or the built-in admin/debug UI of EMQX broker. Or the handy command line mosquitto_sub and mosquitto_pub, which are also used by the Updates2MQTT health check.

Home Assistant

Checklist

(All of these can be checked and changed via the Home Assistant UI.)

  • HA is configured with an MQTT integration
  • MQTT broker host and port is the same on HA as Updates2MQTT
    • Updates2MQTT has been tested with Mosquitto and EMQX
  • Automatic Discovery is on
  • The discovery prefix matches Updates2MQTT ( they both default to homeassistant)

See the examples at Home Assistant Configuration

In addition to the base MQTT configuration, Updates2MQTT relies on MQTT Discovery and MQTT Update integrations. All of these have a single set of MQTT Issues.

When configured, each monitored container will have an update entity visible in the Home Assistant Developer Tools and Entities View.

Home Assistant Mosquitto HassOS App

If using the default Mosquitto broker, and Customization switched on, check the ACL configuration has readwrite access give to the Updates2MQTT user for its topics. The HomeAssistant add-in config puts this in the /share/mosquitto directory.

Oddly, the Paho MQTT client used by Updates2MQTT is known to report success even when broker rejects message because of ACL restrictions.

Alternative MQTT Discovery

There’s also an alternative to MQTT Discovery in HA, using plain yaml, the MQTT Update Integration. The BBQKees Boiler Gateway has some detailed steps and examples for MQTT Discovery too.

No Update Button

If there’s an update showing, but no Update button present, then there’s a few reasons, which can be checked directly from the config and log:

  • Config has the allow_pull,allow_restart and allow_build all overridden to False
  • A new version reference can’t be found
  • The compose working directory can’t be found
  • This is sourced from the com.docker.compose.project.working_dir label, which can be seen in docker inspect
  • This only stops restart, not pull, so if allow_pull is on, the Update button will still show
  • The git repo path can’t be found for a local build

The current state of this can be seen in MQTT, the config message will have two extra values as below:

  "command_topic": "updates2mqtt/dockernuc/docker",
  "payload_install": "docker|homarr|install"

Home Assistant Logs

Use the System Log to check for MQTT errors, or for positive confirmation that Update entities have been discovered. The raw log will show more, and allow you to scroll back for hours.

The Logger Integration lets you tweak the levels of specific integrations. This is less useful for Updates2MQTT, since all the work is happening outside of Home Assistant, however it can be useful for general MQTT issues, and the examples in the Home Assistant documentation shows how to tune the MQTT integration.

Docker

More detailed information on the Docker API and compatibility with Docker engine versions can be found at Docker’s own Docker Engine API reference.

updates2mqtt is designed to run on the same host as the containers, so only needs local Docker daemon access. All it needs for that is the volume mapping as below:

Example Docker Compose Snippet
volumes:
  - /var/run/docker.sock:/var/run/docker.sock

Where docker-compose projects are being automatically updated and restarted, one problem can be that earlier versions used a docker-compose command and newer ones use docker compose. There is a v1 and v2 option in the configuration to support this, defaulting to v2.

If the updates2mqtt container is not running as root, then ensure that the user is a member of the local docker group. (If it is running as root, then consider moving to a defined user, see Running as Non-Root).

Docker Help

Best place to start is the docker-py Issues on GitHub, since this is the primary component inside Updates2MQTT.

A simple way of testing if there’s a docker-py issue is to load the client directly from python. This example uses uv to avoid changing local Python environment, use pip or other preferred tool to install if you want instead.

uv run --with docker python3
>>> import docker
>>> docker.__version__
>>> client = docker.from_env()
>>> client.info()['Containers']

This should output the version of the docker package, and the total count of local containers if the connection is good. Updates2MQTT uses at least v7.1.0 of docker for Python API.

Too Many Requests

The Docker Registry API has a limit on how many authenticated requests, and a lower limit for unauthenticated requests, can be made per hour.

Access to the API will back off when this is hit, and discovery will wait until a configurable period passed, which can be configured using default_api_backoff in the docker configuration section, with a value in seconds.

The throttling is determined per registry, so if Docker is throttling it won’t affect gchr.io, private registries or others. They will also throttle if needed, but again the throttle will only affect that specific registry, and other scans will continue.