✨ Darkwood IaExceptionBundle – Wenn Fehler anfangen, sich selbst zu erklären

der 8. Februar 2026

error-page-screenshot.png

Fehler sind nicht das Problem. Schweigen ist es.

Jeder Backend-Entwickler kennt HTTP-500-Fehler. Sie kommen vor. Sie sind unvermeidlich. Und wenn sie auftreten, verhält sich das System in der Regel wie schon seit Jahrzehnten:

Absturz. Protokoll. Weiter geht's.

Doch was wäre, wenn ein Fehler mehr als nur ein Fehlschlag sein könnte? Was wäre, wenn er sich selbst erklären könnte?

Das ist der Ursprung von Darkwood IaExceptionBundle: ein Symfony-Bundle, das HTTP-500-Fehler um KI-generierte Erklärungen, wahrscheinliche Ursachen und Lösungsvorschläge erweitert und auf Symfony AI aufbaut.

🧭 Die Beobachtung

Moderne Frameworks eignen sich hervorragend für:

  • Auslösen präziser Ausnahmen * Erzeugen von Stacktraces * Exportieren von Protokollen an Observability-Plattformen

Doch die Verantwortung, einen Fehler zu verstehen, liegt weiterhin bei den Menschen.

Das System weiß:

  • welche Ausnahme ausgelöst wurde * wo sie auftrat * unter welchen Bedingungen

Doch es bleibt stumm. Der Entwickler muss die Bedeutung aus den Fragmenten rekonstruieren.

🧠 Eine einfache Idee

Statt zu fragen:

Wie beheben wir Fehler automatisch?

Wir haben eine bescheidenere Frage gestellt:

Was wäre, wenn das System das Geschehene in menschlichen Worten erklären könnte?

Nicht um Debugging-Tools zu ersetzen. Nicht um etwas zu reparieren. Sondern lediglich um Hypothesen schneller zu formulieren.

⚙️ Warum Symfony?

Symfony ist für solche Experimente in einzigartiger Weise geeignet:

  • eine einzige, klar definierte Laufzeitumgebung * ein expliziter kernel.exception-Erweiterungspunkt * eine Kultur von optionalen Bundles * und jetzt ein erstklassiger Integrationspunkt über *Symfony AI

Dies ist keine „Kernfunktion des Frameworks“ – und das sollte es auch nicht sein. Sie muss optional, begrenzt und reversibel bleiben.

🧩 Was das Paket beinhaltet (und was nicht beinhaltet)

✅ Was es bewirkt

Bei einem HTTP-500-Fehler kann das Bundle Folgendes generieren:

  • eine verständliche englische Erklärung der Ausnahme * wahrscheinliche Ursachen * Lösungsvorschläge / nächste Schritte * eine Konfidenzbewertung * eine Fehler-ID zur Korrelation

❌ Was es nicht tut

  • Es behebt keine Fehler. * Es ersetzt nicht Sentry/Logs. * Es garantiert keine absolute Sicherheit. * Es wird **nur ausgeführt, wenn es aktiviert ist.

Es handelt sich um einen Assistenten, nicht um eine Autoritätsperson.

🔐 Sicherheit geht vor (nicht verhandelbar)

Fehler können sensible Details enthalten. Deshalb ist das Paket standardmäßig so konzipiert, dass es sicher ist:

  • Es werden niemals Header, Cookies, Umgebungsvariablen oder Anfragedaten an das Modell gesendet. * Stacktraces sind standardmäßig ausgeschlossen (optional nur für Entwickler). * Bei einem Fehler oder Timeout der KI wird die standardmäßige 500-Fehlerbehandlung von Symfony wie gewohnt ausgeführt (ausfallsicher). * Der Antwortstatus bleibt 500; nur der Antworttext wird erweitert.

📦 Installation und Verwendung in einem bestehenden Symfony-Projekt

Anforderungen

  • PHP 8.2+ * Symfony 6.4+ (auch kompatibel mit 7.x / 8.x) * Eine konfigurierte symfony/ai-bundle Plattform + Agent

1) Installieren Sie das Bundle

composer require darkwood/ia-exception-bundle

2) Registrieren Sie das Bundle (falls erforderlich)

Falls Symfony Flex es nicht automatisch registriert, fügen Sie es zu config/bundles.php hinzu:

return [ // ... Darkwood\IaExceptionBundle\DarkwoodIaExceptionBundle::class => ['all' => true], ];

3) Symfony AI konfigurieren

Beispielkonfiguration für OpenAI:

# config/packages/ai.yaml ai: platform: openai: api_key: '%env(OPENAI_API_KEY)%' agent: default: model: 'gpt-4o-mini'

4) Aktivieren und konfigurieren Sie das Bundle

# config/packages/darkwood_ia_exception.yaml darkwood_ia_exception: enabled: true only_status_codes: [500] agent: 'ai.agent.default' timeout_ms: 800 cache_ttl: 600 cache: 'cache.app' include_trace: false

5) Timeout ordnungsgemäß durchsetzen

Um ein Timeout auf der HTTP-Ebene zu gewährleisten, konfigurieren Sie einen HTTP-Client mit eingeschränktem Gültigkeitsbereich für Ihre KI-Plattform:

# config/packages/ai.yaml framework: http_client: scoped_clients: ai.timeout_client: base_uri: 'https://api.openai.com' timeout: 0.8

ai: platform: openai: api_key: '%env(OPENAI_API_KEY)%' http_client: 'ai.timeout_client'

🧾 Ausgabeformate

JSON (für APIs)

Wenn die Anfrage Accept: application/json enthält, gibt das Bundle strukturiertes JSON wie folgt zurück:

{
  "error_id": "a1b2c3d4e5f6g7h8",
  "english_exception": "Die Datenbankverbindung ist fehlgeschlagen oder eine erforderliche Tabelle fehlt.",
  "probable_causes": ["..."],
  "suggested_fixes": ["..."],
  "confidence": 0.85
}

HTML (Standard)

Andernfalls wird eine HTML-Seite gerendert, die Folgendes anzeigt:

  • Fehler-ID * KI-Erklärung * Ursachen & empfohlene nächste Schritte * Konfidenzwert * ursprüngliche Ausnahmeklasse/Meldung * Hinweis, dass die Ergebnisse Hypothesen sind

🧠 Abschließender Gedanke

Wir haben jahrelang daran gearbeitet, Systeme widerstandsfähiger zu machen. Wir haben Protokolle, Dashboards und Warnmeldungen verbessert.

Vielleicht ist der nächste Schritt einfacher:

Systeme sollten besser darin werden, sich selbst zu erklären.

Nicht um Entwickler zu ersetzen – sondern um ihnen zu helfen, schneller und mit besserem Kontext zu denken.