42 Build Troubleshooting

Build-Prozesse sind deterministisch – zumindest in der Theorie. In der Praxis gehören Build-Fehler zu den häufigsten Störungen in containerisierten Entwicklungs- und Deployment-Workflows. Sie reichen von trivialen Copy-Konflikten über nondeterministische Paketinstallationen bis hin zu subtilen Fehlerbildern, die aus Caching, Layer-Struktur oder Rootless-Einschränkungen entstehen. Podman und Buildah liefern für diese Fälle ein hohes Maß an Transparenz, doch erfolgreiche Fehleranalyse erfordert ein Verständnis der zugrunde liegenden Mechanismen.

42.1 Fehlerkategorien verstehen

Build-Probleme lassen sich grob in vier Klassen einteilen:

Die Herausforderung besteht darin, diese Kategorien schnell zu erkennen und zielgerichtet zu diagnostizieren.

42.2 Syntaktische Fehler: früh, eindeutig, aber oft übersehen

Syntaxfehler sind die einfachste Kategorie. Buildah bricht ab, sobald eine Dockerfile-Anweisung nicht interpretiert werden kann. Häufige Fälle:

Eine Besonderheit: Buildah interpretiert manche Grenzfälle strenger als der Docker-Daemon. Das ist kein Nachteil, sondern eine Folge des präziseren Parsing-Modells.

Ein Tipp: Dockerfiles nicht als „Shelltexte“ behandeln. Sie folgen einer eigenen Grammatik, und ein fehlerhaft gesetzter Backslash kann den gesamten Build zerstören.

42.3 Kontextfehler: das unsichtbare Problem

Kontextfehler entstehen durch den Build-Kontext – also Dateien, die beim Build zur Verfügung stehen oder eben nicht.

Typische Symptome:

Viele dieser Fehler treten nicht im Dockerfile auf, sondern im Vorfeld: .containerignore ist nicht gepflegt oder existiert nicht.

Ein praktischer Trick: Vor dem Build den Kontext manuell inspizieren.

podman build --log-level=debug .

Das Debug-Log zeigt, welche Dateien tatsächlich gepackt und transferiert werden. Diese Einsicht allein löst 30–40 % aller Build-Probleme.

42.4 Laufzeitfehler: RUN schlägt fehl

RUN-Kommandos sind die Hauptquelle komplexer Buildfehler. Innerhalb des Build-Containers läuft eine „Mini-Linux-Welt“, deren Unterschiede zum Host oft unterschätzt werden.

Typische Ursachen:

Ein wichtiger Hinweis: DNS-Probleme und Netzwerkfehler zeigen sich häufig erst in RUN-Schritten. Podman führt Builds isoliert aus, was bedeutet, dass der Build-Container eigene Network-Namensräume besitzt. Firewalls, Proxies oder lokale Resolv-Konfigurationen spielen hier eine größere Rolle als erwartet.

Werkzeuge zur Diagnose:

42.5 Cache-Probleme: wenn Builds sich „falsch“ verhalten

Caching ist oft der größte Unsicherheitsfaktor. Ein Build, der gestern lief, kann heute hängen oder alte Layer wiederverwenden, obwohl Code geändert wurde. Häufige Ursachen:

Ein guter Ansatz ist das schrittweise Deaktivieren des Caches:

podman build --no-cache .

Wenn der Build dann stabil läuft, liegt das Problem im Cache-Semantik.

Debugging-Ansatz:

  1. podman history <image>
  2. prüfen, welche Layer identisch sind
  3. feststellen, welche Befehle wiederverwendet wurden
  4. COPY- und RUN-Blöcke reorganisieren

Caching-Probleme sind selten technisch mysteriös – sie sind ein Hinweis darauf, dass das Dockerfile konzeptionell unklar strukturiert ist.

42.6 Rootless-spezifische Fehler

Rootless-Builds bringen eine eigene Fehlerklasse mit sich:

Das Debugging beginnt häufig mit:

podman info | grep -i overlay

Typische Lösungsmuster:

42.7 Multi-Stage Troubleshooting: Fehler lokalisieren

Multi-Stage Builds erleichtern saubere Architektur – aber sie erschweren Fehleranalyse, weil Fehler häufig aus Stage 1 stammen, die erst später auffallen.

Beispiel:

Strategie:

  1. Builder-Stage einzeln testen:

    podman build --target builder-stage .

  2. Container aus der Builder-Stage starten:

    podman run -it <builder-image> sh

  3. Dateisystem inspizieren

Diese schrittweise Analyse verhindert, dass Fehler erst im finalen Schritt sichtbar werden.

42.8 Debugging mit intermediären Containern

Podman bietet ein oft übersehenes Feature: Build-Stages lassen sich inspizieren, bevor sie finalisiert werden.

--layers zeigt an, welche Layer zwischengespeichert werden. --target erlaubt Builds bis zu einer definierten Stage.

Noch effektiver: ein Build-Container kann während der Ausführung „eingefroren“ werden, indem man die Buildah-API direkt verwendet:

buildah from ...
buildah run ...
buildah copy ...

Dadurch entsteht ein Build, der an jeder Stelle inspiziert werden kann – ideal für fehlerhafte RUN-Kommandos oder Paketinstallationen.

42.9 Netzwerkprobleme während Builds

DNS-Probleme sind die am häufigsten falsch diagnostizierten Buildfehler. Symptome:

Die Ursache ist selten der Build selbst. Typische Fehlerbilder:

Workarounds:

42.10 Debugging durch Minimalisierung

Viele Build-Probleme werden lösbar, wenn der Build reduziert wird. Der Trick:

Beispiel:

Minimal beginnen:

FROM alpine:3.20
RUN apk update

Wenn der Fehler hier bereits auftritt, liegt er auf Systemebene. Wenn nicht, liegt er im eigenen Projekt.

Diese „Entschlackung“ ist oft effizienter als das stundenlange Interpretieren von Logs.

42.11 Werkzeuge zur Build-Analyse

Podman und Buildah bieten mehrere Hilfsmittel:

Diese Werkzeuge decken fast alle Fehlerszenarien ab, wenn man sie systematisch einsetzt.