Skip to content

Troubleshooting

Jump to bottom
Farukk57 edited this page Apr 19, 2026 · 1 revision

Troubleshooting

Container won't start

Permission error on /config/containers.yml:

PermissionError: [Errno 13] Permission denied: '/config/containers.yml'

The container runs as UID 1000. Fix with:

chmod o+r config/containers.yml
chmod o+r config/

Null bytes in .env:

failed to read .env: unexpected character "\x00"

The .env file was saved in UTF-16 encoding. Fix with:

python3 -c "
content = open('.env', 'rb').read()
clean = content.replace(b'\x00', b'')
open('.env', 'wb').write(clean)
"

To prevent this, always edit .env directly on the NAS with nano rather than copying from a Windows machine.

openai module not found:

ModuleNotFoundError: No module named 'openai'

Rebuild the image to install the new dependency:

docker compose up -d --build

No notifications being sent

Check the logs first:

docker logs release-notifier | tail -30

NTFY_URL not set — add NTFY_URL to your .env.

HASS_URL or HASS_TOKEN not set — add both to your .env.

notification already sent -- skipping — the version is already in notified.json. This is normal deduplication. To re-test, clear it:

echo '{}' > data/notified.json

already at vX.X.X — the container is already on the latest version. To force a notification for testing, edit data/state.json and change the version to something older, then trigger a manual check.

AI summary unavailable

AI provider error (Claude): Error code: 529 — Anthropic's API is temporarily overloaded. The notification is still sent without a summary. Retries happen automatically next check cycle.

AI client not initialised at startup — the API key is missing or the wrong AI_PROVIDER is set. Check your .env and that the env var is passed through in docker-compose.yml.

Ollama model not found warning — run ollama pull your-model-name on the machine running Ollama before starting release-notifier.

Digest tracking shows unknown

This is expected for some images:

  • LinuxServer images (lscr.io/linuxserver/...) append -ls### to their tags. The version tag from GitHub doesn't match the Docker Hub tag format, so the digest lookup returns unknown.
  • Jellyseerr — Docker Hub returns 404 for version tags.
  • Duplicati — tag format v2.x.x_stable_DATE doesn't match Docker Hub tags.

These are unfixable without changes upstream. The notification is still sent correctly — only the pull status indicator is affected.

notified.json corruption

Symptoms: JSONDecodeError in logs, check cycle fails.

Fix:

echo '{}' > data/notified.json
docker restart release-notifier

This clears the deduplication log. The next check cycle will send notifications for all containers that have newer versions than what's in state.json.

Home Assistant notifications not arriving

400 Bad Request in logs:

Client error '400 Bad Request' for url '.../notify/mobile_app_...'

The HASS_NOTIFY_SERVICE value is wrong. Check it exactly matches what appears in HA → Developer tools → Actions → search notify.mobile_app.

Notifications arrive but don't appear in HA bell: The HA bell only shows persistent notifications. If the mobile push arrived but nothing is in the bell, the persistent notification call may have failed. Check the logs for HA persistent notification error.

Critical alerts not bypassing silent mode on iOS: Go to Settings → Notifications → Home → Critical Alerts → On.

Manual check returns 404

You may be hitting a different service on port 8080. Use the internal address or add Content-Length: 0:

curl -X POST http://localhost:8080/api/check \
  -H "X-API-Key: your_key" \
  -H "Content-Length: 0"

Checking which version is running

docker exec release-notifier python3 -c "import main; print('OK')"
curl http://localhost:8080/api/health | python3 -m json.tool

Clone this wiki locally