florian.wilde/betreuungs-cockpit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 22 Wiki Activity

Speicherfehler sagen nicht, was zu tun ist — und fallen erst beim ersten Dokument auf #44

New Issue
Closed
opened 2026-09-01 13:43:02 +00:00 by florian.wilde · 1 comment
florian.wilde commented 2026-09-01 13:43:02 +00:00
Owner
Copy Link
Copy Source

Problem

Beim Ablegen eines Schreibens zeigt die Oberfläche:

Das Schreiben konnte nicht abgelegt werden.

Das ist alles. Die tatsächliche Ursache steht nur im Containerlog (console.error in src/server/actions/schreiben.ts:231). Ohne Serverzugang ist der Fehler nicht zu deuten; mit Serverzugang muss man erst wissen, wo man sucht.

In einer echten Fehlersuche am 31.08.2026 lagen nacheinander drei verschiedene Ursachen hinter derselben Meldung:

  1. NoSuchBucket — der Ablagebereich war nie angelegt worden
  2. falscher S3_ENDPOINT — die Anwendung sprach mit einem fremden Anbieter
  3. NotImplemented — serverseitige Verschlüsselung ohne KMS (siehe #42)

Jedes Mal derselbe Satz. Die Suche dauerte entsprechend.

Zwei Dinge fehlen

1. Verständliche Meldungen. Die häufigen Speicherfehler sollen sagen, was los ist und was zu tun ist — ohne Interna preiszugeben:

Fehler Sinngemäß
NoSuchBucket Der Ablagebereich im Objektspeicher fehlt. Siehe INSTALLATION.md, Schritt 6.
NotImplemented (SSE) Der Objektspeicher unterstützt die angeforderte Verschlüsselung nicht.
AccessDenied, SignatureDoesNotMatch Die Zugangsdaten zum Objektspeicher stimmen nicht.
Netzwerkfehler Der Objektspeicher ist nicht erreichbar.

Betrifft nicht nur schreiben.ts, sondern alle Stellen, die ablegen: Dokumenten-Upload, Berichte, Serienlauf.

2. Ein Startcheck. Beim Hochfahren einmal gegen den Speicher prüfen: erreichbar, Bereich vorhanden, Schreibrecht. Das Ergebnis gehört ins Log und nach /api/gesundheit. Heute fällt ein kaputt konfigurierter Speicher erst auf, wenn jemand ein Dokument ablegen will — im Zweifel Wochen nach der Installation, und dann mitten in der Arbeit.

Der Check darf den Start nicht verhindern: Eine Anwendung, die wegen des Speichers nicht hochkommt, ist schlimmer als eine, die ihn meldet.

Akzeptanzkriterien

  • Jeder der vier Fälle oben erzeugt eine eigene, verständliche Meldung in der Oberfläche.
  • Die technische Ursache steht weiterhin im Log, nicht in der Meldung.
  • /api/gesundheit weist den Speicherzustand aus.
  • Beim Start erscheint eine Logzeile mit dem Ergebnis des Checks; bei einem Fehler deutlich als Warnung.
  • Unit-Tests bilden die Fehlerzuordnung ab.
## Problem Beim Ablegen eines Schreibens zeigt die Oberfläche: > Das Schreiben konnte nicht abgelegt werden. Das ist alles. Die tatsächliche Ursache steht nur im Containerlog (`console.error` in `src/server/actions/schreiben.ts:231`). Ohne Serverzugang ist der Fehler nicht zu deuten; mit Serverzugang muss man erst wissen, wo man sucht. In einer echten Fehlersuche am 31.08.2026 lagen nacheinander **drei verschiedene** Ursachen hinter derselben Meldung: 1. `NoSuchBucket` — der Ablagebereich war nie angelegt worden 2. falscher `S3_ENDPOINT` — die Anwendung sprach mit einem fremden Anbieter 3. `NotImplemented` — serverseitige Verschlüsselung ohne KMS (siehe #42) Jedes Mal derselbe Satz. Die Suche dauerte entsprechend. ## Zwei Dinge fehlen **1. Verständliche Meldungen.** Die häufigen Speicherfehler sollen sagen, was los ist und was zu tun ist — ohne Interna preiszugeben: | Fehler | Sinngemäß | |---|---| | `NoSuchBucket` | Der Ablagebereich im Objektspeicher fehlt. Siehe INSTALLATION.md, Schritt 6. | | `NotImplemented` (SSE) | Der Objektspeicher unterstützt die angeforderte Verschlüsselung nicht. | | `AccessDenied`, `SignatureDoesNotMatch` | Die Zugangsdaten zum Objektspeicher stimmen nicht. | | Netzwerkfehler | Der Objektspeicher ist nicht erreichbar. | Betrifft nicht nur `schreiben.ts`, sondern alle Stellen, die ablegen: Dokumenten-Upload, Berichte, Serienlauf. **2. Ein Startcheck.** Beim Hochfahren einmal gegen den Speicher prüfen: erreichbar, Bereich vorhanden, Schreibrecht. Das Ergebnis gehört ins Log und nach `/api/gesundheit`. Heute fällt ein kaputt konfigurierter Speicher erst auf, wenn jemand ein Dokument ablegen will — im Zweifel Wochen nach der Installation, und dann mitten in der Arbeit. Der Check darf den Start **nicht** verhindern: Eine Anwendung, die wegen des Speichers nicht hochkommt, ist schlimmer als eine, die ihn meldet. ## Akzeptanzkriterien - Jeder der vier Fälle oben erzeugt eine eigene, verständliche Meldung in der Oberfläche. - Die technische Ursache steht weiterhin im Log, nicht in der Meldung. - `/api/gesundheit` weist den Speicherzustand aus. - Beim Start erscheint eine Logzeile mit dem Ergebnis des Checks; bei einem Fehler deutlich als Warnung. - Unit-Tests bilden die Fehlerzuordnung ab.
florian.wilde added the in-arbeit label 2026-09-01 14:17:21 +00:00
florian.wilde started working 2026-09-01 14:17:34 +00:00
florian.wilde worked for 13 minutes 2026-09-01 14:31:20 +00:00
florian.wilde commented 2026-09-01 14:32:11 +00:00
Author
Owner
Copy Link
Copy Source

🚀 Umgesetzt und nach main übernommen.

Vorgehen

  1. src/lib/speicher/fehler.ts übersetzt die vier bekannten Fälle. Grundsatz: Es wird nichts durchgereicht, was der Speicher sagt — fremde Fehlertexte tragen Hostnamen, Eimernamen und Anfragekennungen.
  2. Eingebunden in schreiben.ts und dokumente.ts — die beiden Stellen, an denen Benutzer eine Ablage anstoßen.
  3. src/lib/speicher/pruefung.ts: schreibt eine Probedatei, liest sie zurück, räumt sie weg.
  4. Ergebnis in /api/gesundheit und als Logzeile.

Zwei Umwege, die ich nehmen musste

Kein instrumentation.ts. Der naheliegende Starthaken wird auch für die Edge-Laufzeit gebündelt; über die Treiber landet node:path in einem Bündel, in dem es das nicht gibt, und der Build schlägt fehl. Ich habe es gebaut, den Fehler gesehen und umgestellt. Die Prüfung hängt jetzt an der Gesundheitsabfrage — die der Healthcheck ohnehin ab 40 s nach dem Start aufruft, das Ergebnis ist also dasselbe.

Kein 503 bei gestörtem Speicher. Sonst startet der Healthcheck den Behälter neu und macht die ganze Akte unerreichbar — wegen eines Teils, den ein Neustart nicht repariert.

Ein eigener Fehler, beim Testschreiben gefunden. Die Codeermittlung las name vor code. Bei einem Node-Netzwerkfehler steht in name schlicht 'Error' — der echte Code wäre nie erreicht worden, und ECONNREFUSED hätte weiterhin die allgemeine Meldung ergeben. Der Test hat es aufgedeckt, bevor es jemand im Betrieb tut.

Geprüft: 760 Unit-Tests · tsc · Lint · vollständiger Produktions-Build · drei Mutationen, jede wird rot.

Was du davon siehst: Wäre der Fehler von gestern heute aufgetreten, stünde in der Oberfläche „Im Objektspeicher fehlt der Ablagebereich … siehe INSTALLATION.md, Schritt 6" statt „Das Schreiben konnte nicht abgelegt werden." Und beim Blick auf /api/gesundheit hättest du es schon vorher gesehen.

Pull Request: #52 (gemergt)

🚀 **Umgesetzt und nach `main` übernommen.** <!-- claude-status pr: 52 --> **Vorgehen** 1. `src/lib/speicher/fehler.ts` übersetzt die vier bekannten Fälle. Grundsatz: Es wird **nichts** durchgereicht, was der Speicher sagt — fremde Fehlertexte tragen Hostnamen, Eimernamen und Anfragekennungen. 2. Eingebunden in `schreiben.ts` und `dokumente.ts` — die beiden Stellen, an denen Benutzer eine Ablage anstoßen. 3. `src/lib/speicher/pruefung.ts`: schreibt eine Probedatei, liest sie zurück, räumt sie weg. 4. Ergebnis in `/api/gesundheit` und als Logzeile. **Zwei Umwege, die ich nehmen musste** *Kein `instrumentation.ts`.* Der naheliegende Starthaken wird auch für die Edge-Laufzeit gebündelt; über die Treiber landet `node:path` in einem Bündel, in dem es das nicht gibt, und der Build schlägt fehl. Ich habe es gebaut, den Fehler gesehen und umgestellt. Die Prüfung hängt jetzt an der Gesundheitsabfrage — die der Healthcheck ohnehin ab 40 s nach dem Start aufruft, das Ergebnis ist also dasselbe. *Kein 503 bei gestörtem Speicher.* Sonst startet der Healthcheck den Behälter neu und macht die ganze Akte unerreichbar — wegen eines Teils, den ein Neustart nicht repariert. **Ein eigener Fehler, beim Testschreiben gefunden.** Die Codeermittlung las `name` vor `code`. Bei einem Node-Netzwerkfehler steht in `name` schlicht `'Error'` — der echte Code wäre nie erreicht worden, und `ECONNREFUSED` hätte weiterhin die allgemeine Meldung ergeben. Der Test hat es aufgedeckt, bevor es jemand im Betrieb tut. **Geprüft:** 760 Unit-Tests · `tsc` · Lint · vollständiger Produktions-Build · drei Mutationen, jede wird rot. **Was du davon siehst:** Wäre der Fehler von gestern heute aufgetreten, stünde in der Oberfläche „Im Objektspeicher fehlt der Ablagebereich … siehe INSTALLATION.md, Schritt 6" statt „Das Schreiben konnte nicht abgelegt werden." Und beim Blick auf `/api/gesundheit` hättest du es schon vorher gesehen. **Pull Request:** #52 (gemergt)
florian.wilde removed the in-arbeit label 2026-09-01 14:32:18 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
blockiert
Offene Rueckfrage, Uhr steht
 in-arbeit
Claude arbeitet daran, Stopwatch laeuft
 zu-testen
Umgesetzt, PR offen, wartet auf Test
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
florian.wilde (Florian Wilde)
No Assignees
1 Participants
Notifications
Total Time Spent: 13 minutes
florian.wilde
13 minutes
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: florian.wilde/betreuungs-cockpit#44