Fehlerbehebung

Container startet nicht

”Conflict. The container name is already in use”

Docker

docker rm -f devcontainer
docker compose up -d

Podman

podman rm -f devcontainer
podman-compose up -d

KI-Tools funktionieren nicht

”claude: command not found”

Das Image ist möglicherweise veraltet. Laden Sie das neueste herunter und starten Sie neu:

Docker

docker compose pull
docker compose up -d

Podman

podman-compose pull
podman-compose up -d

Claude zeigt “Not logged in”

Der Entrypoint befüllt ~/.claude.json mit Onboarding-Flags. Falls die Datei fehlt:

echo '{"hasCompletedOnboarding": true}' > ~/.claude.json

Claude zeigt “Invalid API key”

Prüfen Sie, welcher Wert tatsächlich gesetzt ist:

echo "$ANTHROPIC_API_KEY"

Häufige Ursachen:

• LiteLLM-Proxy-Schlüssel fehlt oder ist ungültig — Wenn Sie den Proxy-Modus verwenden, stellen Sie sicher, dass LITELLM_API_KEY in .env die korrekten Proxy-Anmeldedaten enthält. Starten Sie dann den Container neu, damit der Entrypoint ANTHROPIC_API_KEY ableiten kann.
• OAuth-Token oder Proxy-Modus-Konflikt — Verwenden Sie genau einen Authentifizierungsmodus. Wenn CLAUDE_CODE_OAUTH_TOKEN gesetzt ist, hat es Vorrang vor dem LiteLLM-Proxy-Modus.

API-Anfragen schlagen mit 401 fehl

Prüfen Sie, ob Ihr API-Schlüssel korrekt gesetzt ist:

echo "$ANTHROPIC_API_KEY"

Überprüfen Sie die Funktion durch einen direkten Aufruf an Ihren Anbieter.

Claude meldet “model not found”

Das Modell wird durch Ihren Anbieter und API-Schlüssel bestimmt. Prüfen Sie die Dokumentation Ihres Anbieters für verfügbare Modelle.

GitHub CLI

”gh: not authenticated”

Die gh-CLI benötigt eine GH_TOKEN-Umgebungsvariable. Fügen Sie diese Ihrer .env-Datei hinzu:

GH_TOKEN=ghp_your-token-here

Erstellen Sie ein Token unter github.com/settings/tokens. Feingranulare Tokens (empfohlen) oder klassische Tokens mit repo-Berechtigung funktionieren beide. Starten Sie den Container nach der Aktualisierung von .env neu.

HTTPS-Git-Clone schlägt mit 401 fehl

Wenn GH_TOKEN gesetzt ist, führt der Entrypoint gh auth setup-git aus, um den Git-Credential-Helper für HTTPS zu konfigurieren. Falls HTTPS-Operationen fehlschlagen:

1. Überprüfen Sie, ob das Token gültig ist: gh auth status
2. Prüfen Sie, ob der Credential-Helper konfiguriert ist: git config --global credential.helper
3. Starten Sie den Container neu, um den Entrypoint erneut auszuführen

SSH vs. HTTPS

Beide Authentifizierungsmethoden können im Container koexistieren:

• SSH (SSH_PRIVATE_KEY in .env) — verwendet git@github.com:-URLs. Erforderlich, wenn Ihre Organisation SSH vorschreibt.
• HTTPS (GH_TOKEN in .env) — verwendet https://github.com/-URLs. Einfachere Einrichtung, keine Schlüsselverwaltung.

Wenn beide konfiguriert sind, verwendet Git das Protokoll, das zur Remote-URL passt. Um einen bestehenden Klon umzustellen:

# SSH zu HTTPS
git remote set-url origin https://github.com/owner/repo.git

# HTTPS zu SSH
git remote set-url origin git@github.com:owner/repo.git

Berechtigungsprobleme

”Permission denied” bei /workspace oder /home

sudo chown -R $(id -u):$(id -g) /workspace ~

npm install schlägt mit EACCES fehl

Der Entrypoint konfiguriert automatisch ein benutzerbeschreibbares npm-Global-Prefix unter ~/.npm-global, sodass npm install -g-Befehle zur Laufzeit ohne sudo funktionieren sollten. Falls weiterhin EACCES-Fehler auftreten, wenden Sie die Korrektur manuell an:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"

Build-Probleme

Build dauert sehr lange

Der erste Build lädt das Basis-Image herunter (~1 GB). Nachfolgende Builds verwenden den Cache. Falls es jedes Mal langsam ist:

Docker

docker builder prune

Podman

podman builder prune

“No space left on device”

Docker

docker system prune -a --volumes

Podman

podman system prune -a --volumes

Warnung: Dies entfernt alle ungenutzten Container, Images und Volumes — nicht nur die dieses Projekts.

Netzwerk

Kein Internetzugang aus dem Container heraus

ping -c 1 8.8.8.8
nslookup google.com
curl -I https://github.com

Docker

Falls DNS fehlschlägt, fügen Sie auf dem Host in /etc/docker/daemon.json hinzu:

{
  "dns": ["8.8.8.8", "8.8.4.4"]
}

Starten Sie dann Docker neu.

Podman

Falls DNS fehlschlägt, konfigurieren Sie DNS innerhalb der Podman-Maschine:

podman machine ssh
sudo sh -c 'echo "nameserver 8.8.8.8" > /etc/resolv.conf'
exit

Oder fügen Sie DNS-Einstellungen in ~/.config/containers/containers.conf auf dem Host hinzu:

[containers]
dns_servers = ["8.8.8.8", "8.8.4.4"]

Starten Sie dann Podman neu: podman machine stop && podman machine start.

Remote-Anzeige (noVNC)

Schwarzer Bildschirm in noVNC

Xvfb wurde möglicherweise nicht gestartet. Prüfen Sie innerhalb des Containers:

ps aux | grep Xvfb

Falls nicht aktiv, überprüfen Sie, dass ENABLE_VNC nicht auf false gesetzt ist, und starten Sie den Container neu.

”Cannot open display” oder “No display”-Fehler

Die Umgebungsvariable DISPLAY ist möglicherweise nicht gesetzt. Überprüfen Sie:

echo "$DISPLAY"

Der Wert sollte :99 sein. Falls leer, fügen Sie DISPLAY=:99 zu Ihrer .env oder devcontainer.json hinzu und starten Sie neu.

Port 6080 — Verbindung abgelehnt

noVNC läuft möglicherweise nicht. Prüfen Sie innerhalb des Containers:

ps aux | grep -E 'novnc|websockify'

Falls nicht aktiv, überprüfen Sie, ob ENABLE_VNC auf true gesetzt ist (Standardwert), und prüfen Sie die Container-Logs:

Docker

docker compose logs dev | grep -i vnc

Podman

podman-compose logs dev | grep -i vnc

Port 6080 wird bereits verwendet

Ändern Sie den Host-Port in docker-compose.yml:

ports:
  - "127.0.0.1:16080:6080"

Chrome DevTools MCP

Chrome Remote-Debugging reagiert nicht

Die gemeinsam genutzte Chrome-Instanz sollte auf Port 9222 laufen. Prüfen Sie innerhalb des Containers:

# Läuft Chrome?
curl http://localhost:9222/json/version

# Chrome-Logs prüfen
cat ~/.local/share/chrome-browser/chrome.log

# Symlink überprüfen
ls -la /opt/google/chrome/chrome

# Chrome manuell neu starten
. /usr/local/lib/chrome-browser.sh
start_chrome_browser

Falls der Symlink fehlt, laden Sie das neueste Image herunter und starten Sie den Container neu.

Browser-Profil-Sperrfehler

Mit der gemeinsam genutzten Browser-Architektur sollten Profil-Sperrfehler nicht auftreten. Falls dennoch einer erscheint, hält möglicherweise ein verwaister Chrome-Prozess die Sperre:

# Verwaiste Chrome-Prozesse beenden
pkill -f 'chrome.*remote-debugging-port' || true

# Sperrdatei entfernen
rm -f ~/.cache/chrome-devtools-mcp/chrome-profile/SingletonLock

# Chrome neu starten
. /usr/local/lib/chrome-browser.sh
start_chrome_browser

Doppelte chrome-devtools-mcp-Tools

Der chrome-devtools-mcp-Server ist jetzt global in ~/.claude/settings.json registriert. Wenn Sie eine projektspezifische .mcp.json haben, die ihn ebenfalls registriert, werden doppelte Tools angezeigt. Entfernen Sie den chrome-devtools-mcp-Eintrag aus projektspezifischen .mcp.json-Dateien:

# Projektspezifische Konfiguration prüfen
cat .mcp.json

Entfernen Sie den chrome-devtools-mcp-Schlüssel aus allen projektspezifischen .mcp.json-Dateien, um die globale Registrierung zu verwenden.

Alles zurücksetzen

Docker

docker compose down -v
docker rm -f devcontainer 2>/dev/null
docker compose pull
docker compose up -d

Podman

podman-compose down -v
podman rm -f devcontainer 2>/dev/null
podman-compose pull
podman-compose up -d

Dies löscht alle Daten in Volumes. Sie müssen Repositories erneut klonen und Tools neu konfigurieren.