Compose-Fehler als Anwendungsfehler

1. Compose: Spring stürzt aufgrund von YAML ab

Wenn Sie den Container-Ready Catalog Service lokal über bootRun starten, haben Sie ein vertrautes Weltbild: Wenn es abstürzt, dann liegt es am Code oder an der Anwendungskonfiguration. Compose bricht diese Gewohnheit sehr sanft und sehr heimtückisch: Sie ändern nicht den Java-Code, sondern die Umgebung, und die Anwendung stürzt ehrlich ab… weshalb es so aussieht, als ob „Spring Boot kaputtgegangen ist“. In Wirklichkeit fungiert Spring in diesem Moment nur als Thermometer, das als erstes die Temperatur anzeigt, aber nicht die Ursache der Erkältung ist.

In Compose tauchen Nachbarn auf: postgres, redis, rabbitmq. Es erscheint das Compose-Netzwerk, Volumes tauchen auf, es gibt mehrere Compose-Dateien (compose.yaml und compose.dev.yaml), und es gibt die Variable-Substitution aus .env. Und auf einmal leben Sie nicht mehr in einer „einzigen Anwendung“, sondern in einer kleinen Stadt. Wenn in der Stadt das Wasser abgestellt wird (Postgres nicht hochkommt), leidet als Erster der, der sich die Hände waschen wollte (Ihre Anwendung), und es wird sich beschweren, als ob „das Badezimmer kaputt“ wäre. Daher kann man in Compose sehr leicht den Ort, an dem der Fehler auftritt, mit seiner Ursache verwechseln.

Der wichtigste praktische Gedanke hier ist einfach: In einer Multi-Container-Umgebung müssen einige Fehler außerhalb der Anwendung genauso sorgfältig diagnostiziert werden wie innerhalb. Wenn Sie einen Stack-Trace in den Logs von app sehen, bedeutet das noch nicht, dass „der Code schuld ist“. Es bedeutet nur eines: app hat ehrlich berichtet, dass ihm nicht gegeben wurde, was es von der Umgebung erwartet.

Bei isolierten Problemen war alles relativ ehrlich: Das Symptom befand sich normalerweise in der Nähe der Ursache. In Compose taucht eine besondere Falle auf – der Fehler lebt im Startmodell, aber den Stack-Trace sehen Sie zuerst in app. Daher ist es wichtig, zwei Ebenen im Kopf zu behalten: was Compose laut YAML starten will und was bereits tatsächlich in den erstellten Containern existiert.

2. YAML vs. Runtime: Was gestartet wurde

Einer der Gründe, warum ein Compose-Fehler so leicht als Anwendungsfehler getarnt wird, ist die Diskrepanz zwischen dem, was Sie denken, dass Sie starten, und dem, was nach allen Verkettungen tatsächlich dabei herauskommt. Im Kopf eines Anfängers ist compose.yaml die Wahrheit, und die Container sind lediglich „seine Ausführung“. Im Leben ähnelt Compose eher einer Kompilierung: Sie haben Quellen (compose.yaml, compose.dev.yaml, .env), und am Ende steht eine „kompilierte“ endgültige Konfiguration. Auf deren Grundlage erstellt Compose die Container.

Hier ist ein kleiner (und nützlicher) Gedankengang: compose.yaml ist wie Java-Code, und docker compose config ist wie Bytecode nach der Kompilierung. Sie können tausendmal auf die Quelle schauen und sagen: „Hier ist alles richtig“, aber gestartet wird das, was nach Substitutionen und Merges entstanden ist.

In der Compose-Welt gibt es oft mehrere Gründe, warum „das Geschriebene“ nicht dem „Erreichten“ entspricht:

Erstens: mehrere Compose-Dateien. In unserem Kurs ist das Kanon: Es gibt compose.yaml und compose.dev.yaml, wobei die zweite Datei die erste überschreibt. Wenn Sie nur compose.yaml betrachten, sehen Sie die Hälfte des Bildes (ungefähr so, als würden Sie nur die ungeraden Seiten eines Buches lesen und sich wundern, dass die Handlung seltsam ist).

Zweitens: Variable-Substitution. Compose kann ${SOME_VAR} durch einen leeren String ersetzen, wenn die Variable nicht gesetzt ist, und das erzeugt sehr „plausible“ Fehler auf Anwendungsebene. Und ja, die Anwendung wird ehrlich sagen: „Kann DataSource nicht konfigurieren“, aber die Ursache ist, dass die Verbindungszeichenkette durch die Substitution leer geworden ist.

Drittens: „Alte Container“. Sie haben die Umgebungsvariablen oder Volumes im YAML geändert, aber die laufenden Container werden nicht immer automatisch so neu erstellt, wie Sie es intuitiv erwarten. Infolgedessen reparieren Sie das YAML, sehen aber weiterhin das Verhalten der alten Konfiguration.

Und hier kann man leicht zwei verschiedene Wahrheitsquellen verwechseln. docker compose config zeigt das resolved-Startmodell: was Compose aus Dateien, Override und Substitutionen zusammenbaut. docker inspect und, wenn der Container lebt, docker compose exec ... printenv zeigen den tatsächlichen Zustand des bereits erstellten Containers: was er gerade enthält. Nach einer YAML-Änderung können diese Ebenen auseinanderdriften: Die gewünschte Konfiguration ist bereits korrigiert, aber der Container ist noch der alte. Erstellen Sie in einer solchen Situation zuerst den benötigten Service neu und wiederholen Sie dann dieselbe Prüfung.

Daher taucht in der Compose-Diagnose eine separate obligatorische Frage auf: Was wurde genau angewendet?

3. docker compose config: Die gemergte Wahrheit

Wenn Sie aus dieser Lektion genau einen Befehl behalten, dann soll es docker compose config sein. Er ist nicht „für die Schönheit“ oder für DevOps-Schamanismus da. Er zeigt die resolved-Wahrheit über das Startmodell: was Compose aus Dateien, Override und .env zusammenbauen wird. Erst danach vergleichen Sie es mit dem tatsächlichen Zustand der Container, um aufzuhören, mit Ihrer Vorstellungskraft zu streiten.

Der wichtigste Punkt: Wenn Sie zwei Dateien haben, müssen Sie die Konfiguration in derselben Form prüfen, in der Sie den Stack tatsächlich starten. Wenn Sie den Dev-Stand so hochfahren:

# Starte den Stack mit denselben Dateien, die im eigentlichen Dev-Start verwendet werden
docker compose -f compose.yaml -f compose.dev.yaml up

dann sollten Sie die „Wahrheit“ auch so betrachten:

# Zeige die endgültige (gemergte) Konfiguration nach allen Overrides und Substitutionen an
docker compose -f compose.yaml -f compose.dev.yaml config

Dieser Befehl zeigt Ihnen das endgültige YAML nach Substitutionen und Zusammenführung. Danach können Sie mit den Augen nach wichtigen Dingen suchen: welche Ports tatsächlich veröffentlicht wurden, welche Umgebungsvariablen tatsächlich übergeben werden, welche Volumes tatsächlich eingehängt sind, welche depends_on-Bedingungen tatsächlich gesetzt sind.

Wenn nach einer YAML-Korrektur config bereits die richtigen Umgebungsvariablen oder Mounts anzeigt, die Anwendung sich aber weiterhin wie zuvor verhält, ist das kein Widerspruch. Es ist Zeit, den tatsächlichen Zustand über docker inspect zu vergleichen und den Service neu zu erstellen, anstatt dasselbe YAML noch einmal umzuschreiben.

Eine sehr häufige Tarnung ist, wenn beide YAML-Fragmente „logisch“ aussehen, aber zusammen eine inkompatible Konstruktion ergeben. Zum Beispiel gibt die Basisdatei einen Exportpfad vor, und die Dev-Datei mountet einen anderen Pfad:

# compose.yaml (Fragment)
services:
  app:
    environment:
      # Dies ist der Pfad, in den die Anwendung innerhalb des Containers Dateien schreiben wird
      APP_EXPORT_DIR: /app/exports

# compose.dev.yaml (Fragment)
services:
  app:
    volumes:
      # Links der Pfad auf dem Host, rechts der Pfad innerhalb des Containers (hier kann man leicht das Target verwechseln)
      - ./data/exports:/app/export  # Beachte: export, nicht exports

Jedes Stück für sich sieht glaubwürdig aus. Am Ende schreibt die Anwendung nach /app/exports, der Mount ist aber mit /app/export verbunden. Auf der Java-Seite sehen Sie „Datei wurde nicht erstellt“ oder „Permission denied“, und es ist sehr leicht, den Export-Code zu durchsuchen. Dabei ist es ein reines Compose-Problem, und docker compose config zeigt es buchstäblich sofort.

Ein weiteres wichtiges Detail, das Studenten oft verwirrt: .env und environment: sind verschiedene Ebenen. .env ist in Compose in erster Linie an der Substitution von Werten in YAML beteiligt und nicht eine „automatische Übergabe aller Variablen in den Container“. Wenn Sie erwarten, dass „weil .env SPRING_PROFILES_ACTIVE=postgres enthält, der Container das auf jeden Fall bekommt“, könnten Sie eine Überraschung erleben. Überprüfen müssen Sie auf dieselbe Weise: über docker compose config und bei Bedarf über docker exec … printenv.

4. Masken von Compose in den Logs von Spring Boot

In einer Multi-Container-Umgebung wird die Anwendung zum Schaufenster: Sie zeigt den Fehler zuerst an, weil sie als erste „versucht zu arbeiten“. Die Fehlerklasse kann aber auf Compose-Ebene liegen. Um nicht zu raten, ist es hilfreich, einige typische Entsprechungen zwischen „was ich in den Anwendungslogs sehe“ und „was eigentlich in der Compose-Umgebung kaputt sein kann“ im Kopf zu haben.

Unten ist eine kleine Spickzettel-Tabelle. Sehen Sie sie nicht als Nachschlagewerk „für alle Lebenslagen“, sondern eher als schnelle Möglichkeit, eine erste Hypothese zu formulieren und eine kostengünstige Überprüfung auszuwählen.

Beachten Sie die allgemeine Struktur: Fast überall ist die erste Überprüfung nicht „IDE öffnen und nach einem Bug suchen“, sondern „die tatsächlichen Runtime-Parameter ansehen“. In Docker/Compose ist es besonders gefährlich, Symptome aus Gewohnheit zu behandeln: Sie sehen einen Stack-Trace, das Gehirn schaltet automatisch in den Modus „Ich bin Java-Entwickler, also werde ich jetzt Java reparieren“. Besser ist es, für 2 Minuten zum „Umgebungsentwickler“ zu werden und zu bestätigen, dass Sie der Anwendung überhaupt das gegeben haben, was sie erwartet.

Ein besonderes Wort zu Partial Startup, denn das ist eine der plausibelsten Quellen für „falsche“ Fehler. Sie könnten nur app + postgres gestartet haben, aber SPRING_PROFILES_ACTIVE=postgres,cache hinterlassen haben. Die Anwendung wird ehrlich versuchen, sich mit Redis zu verbinden und sich beschweren. In den Logs sieht das aus wie „das Caching ist kaputt“. In Wirklichkeit ist das Problem ein Missverhältnis: Die aktiven Profile verlangen eine Abhängigkeit, die Sie im aktuellen Szenario nicht hochgefahren haben.

Genauso können Sie versehentlich das messaging-Profil aktivieren und RabbitMQ-Fehler erhalten, obwohl Sie in diesem Moment gar nicht Nachrichten debuggen, sondern zum Beispiel den Export in eine Datei. Und wieder: Fehler in den Anwendungslogs, aber die Ursache liegt im Startmodell.

5. Logs mehrerer Services

In einem einzelnen Container ist alles einfach: ein Container, ein Prozess, ein Logstrom. In einem Compose-Stack funktioniert das nicht so, weil Sie mindestens zwei Prozesse haben, die miteinander sprechen, und oft ist die Ursache genau in diesem Dialog versteckt. Daher ist es sehr nützlich zu lernen, Logs als Kette von Ursachen und Wirkungen zu lesen, nicht als eine Sammlung unabhängiger Texte.

In der Praxis sieht das so aus: Sie sehen, dass app „Kann keine Verbindung zu PostgreSQL herstellen“ schreibt. Wenn Sie nur die Logs von app lesen, erhalten Sie einen schönen Stack-Trace und das Gefühl „alles ist schlecht“. Aber wenn Sie gleichzeitig die Logs von postgres lesen, sehen Sie oft eine viel genauere Antwort: Die Datenbank startet noch, die Datenbank hat das Passwort nicht akzeptiert, die Datenbank hat den Benutzer nicht erstellt, die Datenbank ist bei der Migration abgestürzt (je nach Szenario). Die Anwendung ist in diesem Moment nur ein Client, der das Symptom widerspiegelt.

Der einfachste Weg, die Kette zu erfassen, ist die Compose-Variante von Logs:

# Sehen Sie sich die Logs von Client (app) und Abhängigkeit (postgres) gleichzeitig an, um die Ursache-Wirkungs-Kette zu sehen
docker compose logs app postgres

Wenn Sie live zusehen möchten, fügen Sie den Follow-Modus hinzu:

# Follow-Modus ist praktisch, wenn Sie Services neu starten und den Absturz-/Bereitschaftsmoment einfangen
docker compose logs -f app postgres

Und wenn es zu viele Logs gibt (was bei Spring Boot selbst montags vorkommt), hilft ein kurzer „Tail“:

# Nimm nur die letzten Zeilen, um schnell die aktuelle Ursache zu sehen, ohne scrollen zu müssen
docker compose logs --tail=50 app postgres

Hier ist nicht die Anzahl der Flags wichtig, sondern die Gewohnheit: Sobald Sie eine Abhängigkeit haben, sollten Sie immer mindestens zwei Log-Ströme im Kopf haben. Und wenn Sie eine Hypothese aufstellen, fragen Sie nicht „warum ist die Anwendung abgestürzt?“, sondern „wer hat zuerst gesagt, dass etwas nicht stimmt?“

In der Compose-Diagnose ist es manchmal sinnvoll, nicht einmal mit den Logs zu beginnen, sondern mit dem Status der Services:

docker compose ps

Sie erhalten eine Tabelle, in der Sie sehen, welche Container Up, welche Exited sind, welche den Status healthy/starting haben. Wenn postgres noch starting ist, aber app bereits versucht, sich zu verbinden und abstürzt, dann ist das fast ein Lehrbuchfall für Readiness-Probleme. Und wieder: Äußerlich wird es aussehen, als ob „Spring kaputt ist“ – in Wirklichkeit starten Sie den Stack einfach ohne die tatsächliche Bereitschaft der Abhängigkeit.

6. Fehler im resolved YAML

Es gibt eine besondere Klasse von Problemen, die psychologisch am schwierigsten ist: Wenn Sie auf compose.yaml schauen, ist alles perfekt, und selbst ein Kollege neben Ihnen sagt: „Ja, alles in Ordnung.“ Aber der Stack stürzt trotzdem ab. In solchen Fällen ist fast immer das schuld, was die reale Startkonfiguration ist – nicht compose.yaml, sondern das Ergebnis der Zusammenführung mehrerer Dateien und Substitutionen. Das Problem lebt also im resolved YAML.

Das häufigste Szenario ist ein unerwarteter Override in compose.dev.yaml. Sie wollten zum Beispiel im Dev-Modus ein Volume hinzufügen oder einen Debug-Port öffnen, haben aber versehentlich den falschen Abschnitt überschrieben und den Basis-Modus gestört. Das ähnelt stark einer Situation in Java, wo Sie „ein wenig die Konfiguration für Tests ändern“ wollten, aber versehentlich eine Produktionseinstellung überschrieben haben – nur findet es hier auf YAML-Ebene statt.

Die zweite häufige Geschichte ist ein Pfadkonflikt. Bei Mounts in Compose ist der Target-Path innerhalb des Containers entscheidend. Wenn APP_EXPORT_DIR auf einen Ort verweist, das Volume aber woanders eingehängt ist, wird das Verhalten „magisch“ und ärgerlich: Der Export „funktioniert“ (in den Logs sehen Sie Erfolg), aber die Datei ist auf dem Host „nicht da“. Und Sie beginnen, CSV, den Code, die Zugriffsrechte, die Mondphase zu verdächtigen … dabei hätte es gereicht, die beiden Pfade in docker compose config zu vergleichen.

Die dritte Geschichte ist Readiness und depends_on. Wenn Sie in der resolved-Konfiguration sehen, dass Sie condition: service_started haben, bedeutet das nur „der Container Postgres läuft“, aber nicht „PostgreSQL ist bereit, Verbindungen anzunehmen“. Die Anwendung kann durchaus beim Start mit einem Verbindungsfehler abstürzen, und das wird wie ein Startup-Fehler der Anwendung aussehen. Die Ursache ist jedoch, dass das Startmodell nicht auf die Bereitschaft der Abhängigkeit gewartet hat. Das ist eine so häufige Tarnung, dass es nützlich ist, sie mit den Augen zu erkennen.

Hier ist ein Beispiel, das „fast richtig“ aussieht, aber ein flakiges Verhalten erzeugt:

services:
  app:
    depends_on:
      postgres:
        # Container gestartet, aber der Dienst darin kann noch nicht bereit sein
        condition: service_started

Und hier ist eine Variante, die die tatsächliche Abhängigkeit besser ausdrückt:

services:
  app:
    depends_on:
      postgres:
        # Warten auf tatsächliche Bereitschaft (healthcheck), nicht nur auf das Starten des Containers
        condition: service_healthy

Der Unterschied ist klein, aber die Wirkung enorm: Sie hören auf, „zu raten, ob die Datenbank aufgewacht ist“.

Und schließlich – die „unsichtbarste“ Ursache: Die Variable-Substitution hat einen leeren Wert geliefert. Im YAML steht zum Beispiel:

services:
  app:
    environment:
      SPRING_PROFILES_ACTIVE: ${SPRING_PROFILES_ACTIVE}

Wenn die Variable nicht gesetzt ist, kann die endgültige resolved-Konfiguration einen leeren Wert enthalten, und die Anwendung startet in einem ganz anderen Modus als erwartet. Sie erhalten dann den Fehler „gestern hat alles funktioniert, heute nicht“, obwohl sich in Wirklichkeit nur die Umgebung geändert hat, aus der Compose den Wert bezog. docker compose config zeigt Ihnen das „wie es ist“, ohne Fantasie.

7. Mini-Diagnoseschema für Compose-Tarnung

Es ist wichtig, diese Vorlesung nicht in ein vorschnelles „vollständiges Playbook“ zu verwandeln (das werden wir in der nächsten Vorlesung sorgfältig zusammenstellen). Aber ein minimales Schema speziell für die Compose-Tarnung brauchen Sie jetzt schon, um den typischen „IDE-first“-Reflex zu vermeiden.

Sie können sich diese kurze Route merken: Zuerst prüfen Sie das Startmodell, dann den Zustand der Services, dann bauen Sie eine Kette aus den Logs auf, und erst danach gehen Sie in den Container hinein. Das klingt zu rational, also lassen Sie es uns in einem einfachen Flussdiagramm festhalten.

flowchart TD
    A["Fehler trat in der Anwendung innerhalb von Compose auf"] --> B["Sehen uns das resolved-Modell an: docker compose config"]
    B --> C["Sehen uns den Status an: docker compose ps"]
    C --> D["Lesen die Logkette: docker compose logs app + Abhängigkeiten"]
    D --> E{"Ist die Hypothese konkret geworden?"}
    E -->|"Ja"| F["Gezielte Überprüfung: inspect/exec nur nach Bedarf"]
    E -->|"Nein"| G["Präzisieren: Was war das erste Symptom und wo?"]
    F --> H["Eine Korrektur"]
    H --> I["Wiederholung der ursprünglichen Überprüfung"]

In diesem Schema ist wichtig, dass es Sie vor zwei teuren Fehlern schützt. Der erste Fehler: Die Anwendung reparieren, ohne bestätigt zu haben, dass die Umgebung überhaupt mit den Erwartungen übereinstimmt. Der zweite Fehler: „Hundert Prüfungen hintereinander“ durchführen, ohne eine Hypothese formuliert zu haben. Die Compose-Tarnung liebt besonders das Chaos: Je chaotischer Sie das YAML ändern, desto weniger verstehen Sie, warum es besser oder schlechter geworden ist.

Und noch ein kleiner, aber praktischer Punkt: Wenn Sie YAML ändern, stellen Sie sicher, dass Sie die Änderung tatsächlich angewendet haben. Manchmal muss der Service neu erstellt werden, sonst betrachten Sie weiterhin die alte Konfiguration. Das ist keine „Docker-Magie“, sondern einfach Mechanik: Der Container wurde bereits mit bestimmten Umgebungsvariablen und Mounts erstellt, und solange Sie ihn nicht neu erstellen, wird er nicht „von selbst“ anders. Denken Sie bei der Diagnose daran: Sie ändern nicht den Text, Sie ändern die tatsächliche Runtime.

8. Typische Fehler bei der Diagnose von Compose-Tarnungen

Fehler Nr. 1: Nur die Anwendungslogs lesen und die Logs der Abhängigkeiten ignorieren.
Das wirkt natürlich: Sie sind Java-Entwickler, Sie haben einen Stack-Trace in den Logs, also müssen Sie ihn lesen. Aber in einem Compose-Stack spiegelt der Stack-Trace oft nur das Problem des Nachbarn wider. Wenn postgres noch startet oder das falsche Passwort erhalten hat, wird die Anwendung als erste und lauteste abstürzen, aber die Ursache lebt in einem anderen Container.

Fehler Nr. 2: Dem YAML-Fragment vertrauen statt der resolved-Konfiguration.
Wenn Sie compose.yaml und compose.dev.yaml haben, nur eine Datei anzuschauen ist, als würde man einen Bug anhand einer einzigen Methode diagnostizieren, ohne den aufrufenden Code zu lesen. Infolgedessen reparieren Sie etwas, das „sowieso nicht verwendet wird“, während der tatsächliche Override-Wert weiterhin den Start stört. Der Befehl docker compose config spart hier Stunden.

Fehler Nr. 3: Einen Partial-Start durchführen und vergessen, ihn mit den aktiven Spring-Profilen abzugleichen.
Partial-Start ist ein hervorragendes Werkzeug, erfordert aber Disziplin. Wenn Sie nur app + postgres gestartet haben, aber SPRING_PROFILES_ACTIVE cache oder messaging enthält, wird die Anwendung ehrlich auf Redis/RabbitMQ warten und sich beschweren. Das Symptom sieht aus wie „der Cache-/Messaging-Code ist kaputt“, obwohl Sie die Anwendung einfach gebeten haben, in einem Modus zu leben, für den Sie keine Infrastruktur bereitgestellt haben.

Fehler Nr. 4: service_started mit der tatsächlichen Bereitschaft der Abhängigkeit verwechseln.
depends_on mit service_started erzeugt oft das Gefühl „manchmal funktioniert es, manchmal nicht“. Ein Anfänger nimmt das als Zufall wahr oder als „Spring spinnt“. In Wirklichkeit ist es ein Timing: Die Datenbank ist als Container gestartet, aber noch nicht bereit, Verbindungen anzunehmen. Wenn Sie Stabilität wollen, müssen Sie in Compose den tatsächlichen Bereitschaftszustand ausdrücken, nicht nur die Startreihenfolge.

Fehler Nr. 5: Einen Pfad mounten, aber die Anwendung auf einen anderen konfigurieren.
Besonders häufig passiert das mit dem Export-Verzeichnis: In APP_EXPORT_DIR steht ein Wert, in volumes ein anderer Target. Die Anwendung schreibt Dateien „in den Container“, Sie sehen sie nicht auf dem Host und beginnen, den Code oder das CSV-Format zu verdächtigen. Dabei handelt es sich um einen reinen Mismatch im Compose-Modell, der schneller überprüft ist, als jeder Stack-Trace gelesen werden kann.