fotospiel-app/docs/ops/howto-guest-upload-failing.md

id, title, sidebar_label

id	title	sidebar_label
howto-guest-upload-failing	How-to – Gäste können nicht hochladen	Gäste können nicht hochladen

Dieses How‑to beschreibt, wie du vorgehst, wenn Gäste melden, dass sie keine Fotos mehr hochladen können (Fehler im Upload‑Flow oder „hängenbleibende“ Uploads).

1. Problem eingrenzen

Fragen an den Tenant/Support:

• Betrifft es alle Gäste oder nur einzelne?
• Betrifft es alle Events oder nur ein bestimmtes Event?
• Welche Fehlermeldung erscheint im Guest‑Frontend (so genau wie möglich, gerne mit Screenshot)?
• Seit wann tritt das Problem auf? (Zeitfenster)

Diese Informationen bestimmen, ob du in Richtung API/Rate‑Limit, Storage/Queues oder Event‑Konfiguration schauen musst.

2. Basischecks – API & App

1. Public-API Status
   • Teste manuell einen Upload gegen ein Test‑Event oder reproduziere das Problem mit dem betroffenen Join‑Token.
   • Achte auf HTTP‑Statuscodes im Browser‑Network‑Tab (4xx vs. 5xx).
2. App- / Deployment-Status
   • Prüfe in Docker/Dokploy, ob App/Queue/Redis/DB‑Container gesund sind.
   • Schaue in storage/logs/laravel.log nach offensichtlichen Exceptions rund um das gemeldete Zeitfenster.

Wenn die Public‑API generell 5xx liefert, greift eher das Public‑API‑Incident‑Playbook (docs/ops/deployment/public-api-incident-playbook.md).

3. Queues & Upload-Health

Wenn das Problem hauptsächlich Uploads betrifft (andere Funktionen laufen):

1. Queue-Längen prüfen
   • In Horizon:
     • media-storage, media-security und ggf. notifications Queue‑Längen ansehen.
   • In Logs:
     • Warnungen aus storage:check-upload-queues oder storage-jobs suchen.
2. Upload-Health-Command
   • Sicherstellen, dass storage:check-upload-queues regelmäßig läuft (Cron / Scheduler).
   • Manuell ausführen (in der App‑Container‑Shell):

     php artisan storage:check-upload-queues
     

   • Ausgaben/Logs prüfen:
     • Meldungen zu „stalled“ Uploads, Events mit dauerhaft vielen Pending‑Assets.

4. Storage & Limit-Probleme

1. Hot-Storage-Füllstand
   • Prüfen, ob das Storage‑Volume/Bucket nahe an 100 % ist (siehe docs/ops/dr-storage-issues.md).
   • Wenn ja:
     • Archivierung beschleunigen (storage:archive-pending verifizieren).
     • Kurzfristig Speicher vergrößern oder Caches aufräumen.
2. Paket-/Limit-Prüfungen
   • Wenn nur bestimmte Events betroffen sind:
     • Paket‑Limits des Events prüfen (z.B. max_photos/max_guests).
     • Event‑Status (abgelaufen/archiviert?) prüfen.
   • Logs können Fehlercodes liefern wie „photo_limit_exceeded“ – diese deuten auf bewusst ausgelöste Limit‑Sperren hin, nicht auf technische Fehler.

5. Typische Muster & Gegenmaßnahmen

• Hohe Fehlerrate beim Upload (5xx)
  • Hinweis auf API‑/Backend‑Problem:
    • Siehe Public‑API‑Runbook und App‑Logs (Datenbank‑/Redis‑Fehler, Timeouts).
• Uploads bleiben „ewig“ auf „wird verarbeitet“
  • Queues laufen nicht oder media-storage/media-security steckt fest:
    • Horizon prüfen, ob Worker‑Container laufen.
    • Ggf. Worker neu starten und Failed Jobs analysieren.
• Nur ein Event betroffen, andere funktionieren
  • Meist Limit‑ oder Konfig‑Thema (Paket voll, Galerie abgelaufen, Event deaktiviert).
  • Tenant‑Admin‑UI prüfen: Event‑Status, Paket‑Status, Data Lifecycle Einstellungen.

6. Kommunikation

• An Tenant/Support zurückmelden:
  • Was war die Ursache? (z.B. Paket‑Limit, temporäre Überlastung, Storage‑Knappheit).
  • Was wurde getan? (z.B. Paket angepasst, Queues neu gestartet, Storage erweitert).
  • Ob und wie der Tenant/gäste weiteres tun müssen (z.B. Seite neu laden, später erneut probieren).

Für tiefere Ursachen rund um Storage siehe docs/ops/media-storage-spec.md und docs/ops/dr-storage-issues.md.