Fehlerbehebung

Grunddiagnose

cd /opt/ntfy-downloader
docker compose -f compose.image.yaml config -q
docker compose -f compose.image.yaml ps
docker compose -f compose.image.yaml logs --since 15m --no-color
docker system df -v

Zuerst klären, welcher Dienst betroffen ist: ntfy/Download oder Web-UI/ffmpeg.

Container ist unhealthy

Listener prüfen:

docker inspect --format '{{json .State.Health}}' ntfy-downloader
docker compose -f compose.image.yaml logs --since 10m ntfy-downloader

Typische Ursachen:

• fehlende ntfy-Konfiguration
• DOWNLOAD_DIR nicht gemountet oder nicht beschreibbar
• Jobqueue-Volume nicht beschreibbar
• falsche UID/GID

Web-UI prüfen:

docker inspect --format '{{json .State.Health}}' ntfy-webui
docker compose -f compose.image.yaml logs --since 10m ntfy-webui

Typische Ursachen sind fehlende Web-UI-Zugangsdaten oder nicht beschreibbare Thumbnail-/Metadatenpfade.

Volume-Warnung beim Start

Warnung:

volume "..." already exists but was not created by Docker Compose

Im aktuellen compose.image.yaml sind ntfy-state und ntfy-thumbs mit ihren festen Namen als extern deklariert. Damit verwendet Compose bestehende Volumes ohne Warnung. Auf einem neuen Host müssen beide vor dem ersten Start angelegt werden:

docker volume create ntfy-downloader_ntfy-state
docker volume create ntfy-downloader_ntfy-thumbs

Existiert ein externes Volume nicht, bricht Compose bewusst ab, statt ein unerwartetes leeres Volume zu verwenden.

manifest unknown beim Pull

Der Forgejo-Runner hat das SHA-Image noch nicht veröffentlicht oder der SHA ist falsch. Vollständigen SHA prüfen und den erfolgreichen Workflow abwarten:

docker pull git.home.schumbi.de/ralf/ntfy-downloader:<vollstaendiger-sha>

Keine Downloads

• ntfy-Basis-URL, Topic und Zugangsdaten prüfen.
• Sicherstellen, dass die Nachricht eine vollständige http://- oder https://-URL enthält.
• Listener-Logs auf 401/403, Resolver- oder yt-dlp-Fehler prüfen.
• Freien Speicher und Schreibrechte des Downloadverzeichnisses kontrollieren.
• Bei TLS-Fingerprinting YTDLP_IMPERSONATE=chrome verwenden.

Download wird doppelt gemeldet

Die Queue dedupliziert anhand der ntfy-ID. Bei gelöschter oder neuer leerer Jobdatenbank fehlt diese Historie. Kontrollieren, ob wirklich das externe ntfy-state-Volume eingebunden ist und nicht versehentlich ein neues Volume verwendet wird.

Video spielt im Browser nicht

MKV/AVI oder nicht browserkompatible Codecs werden nicht von jedem Browser unterstützt. Datei herunterladen oder einen WhatsApp-kompatiblen MP4-Ausschnitt erzeugen. Der Server transcodiert Originalvideos beim normalen Abspielen nicht.

GIF-Export scheitert oder ist langsam

• Dauer darf zehn Sekunden nicht überschreiten.
• Web-UI-Logs auf ffmpeg-Fehler oder Timeout prüfen.
• GIF_TIMEOUT bei sehr langsamer Hardware erhöhen.
• CPU-/Speicherlimit der Web-UI prüfen.
• GIF bleibt datenintensiv; für Messenger besser WhatsApp-MP4 verwenden.

WhatsApp-Video wird nicht abgespielt

Mit ffprobe prüfen:

ffprobe -v error \
  -show_entries stream=codec_name,profile,pix_fmt,width,height \
  -of json /pfad/zur/datei.mp4

Erwartet werden H.264 Baseline/Constrained Baseline, yuv420p und AAC. Für neue Exporte erzeugt die Anwendung diese Eigenschaften automatisch.

Share-Link liefert 401, 403 oder 410

• Ein Galerie- oder /watch-Link benötigt Basic Auth und ist kein Share-Link.
• Der öffentliche Link muss mit /shared/whatsapp beginnen.
• 403: Signatur passt nicht, oft nach Passwortwechsel oder URL-Manipulation.
• 410: WHATSAPP_SHARE_TTL ist abgelaufen; Export beziehungsweise Link neu erzeugen.
• WEBUI_PUBLIC_URL muss von WhatsApp erreichbar sein.

Gateway Timeout

Aktuelle GIF- und WhatsApp-Exporte starten Hintergrundjobs und leiten sofort auf eine Fortschrittsseite um. Tritt trotzdem ein Gateway Timeout auf:

• prüfen, ob wirklich der aktuelle Image-SHA läuft
• Proxy- und Web-UI-Logs zeitlich vergleichen
• Healthcheck und Ressourcenauslastung kontrollieren
• sicherstellen, dass der Browser die Statusroute regelmäßig abfragen kann

Tags fehlen

• ntfy-metadata-Volume muss eingebunden und beschreibbar sein.
• WhatsApp-MP4s im konfigurierten Ordner werden beim Web-UI-Start automatisch mit WhatsApp nachgetaggt.
• Nach manuellen Dateiverschiebungen außerhalb der Web-UI stimmen gespeicherte relative Pfade nicht automatisch; Verschieben daher bevorzugt in der Web-UI.