Troubleshooting

Troubleshooting

Dieser Leitfaden hilft bei der Lösung häufiger Probleme mit Polycrate.

Docker-Probleme

"Cannot connect to Docker daemon"

Problem: Polycrate kann keine Verbindung zum Docker-Daemon herstellen.

Error: Cannot connect to the Docker daemon at unix:///var/run/docker.sock

Lösungen:

  1. Prüfen Sie, ob Docker läuft: 

    docker ps

  2. Starten Sie Docker: 

    # Linux (systemd)
sudo systemctl start docker

# macOS/Windows
# Starten Sie Docker Desktop

  3. Prüfen Sie Berechtigungen: 

    # Linux - Benutzer zur docker-Gruppe hinzufügen
sudo usermod -aG docker $USER
newgrp docker

  4. Prüfen Sie den Socket-Pfad: 

    ls -la /var/run/docker.sock

"Image not found" oder Pull-Fehler

Problem: Polycrate kann das Workspace-Image nicht finden oder herunterladen.

Error: Error response from daemon: pull access denied for cargo.ayedo.cloud/library/polycrate

Lösungen:

  1. Prüfen Sie Ihre Internetverbindung

  2. Authentifizieren Sie sich bei der Registry: 

    docker login cargo.ayedo.cloud

  3. Verwenden Sie ein anderes Image: 

    polycrate run my-block install --image-ref <alternative-image>

  4. Überspringen Sie den Pull (wenn Image bereits lokal): 

    polycrate run my-block install --pull false

Container startet nicht

Problem: Der Polycrate-Container startet nicht oder stürzt sofort ab.

Lösungen:

  1. Prüfen Sie die Container-Logs: 

    docker logs <container-id>

  2. Prüfen Sie die Polycrate-Logs: 

    ls -la .logs/
cat .logs/<latest-log-file>

  3. Erhöhen Sie den Log-Level: 

    polycrate run my-block install --loglevel 2

  4. Testen Sie den Container manuell: 

    docker run -it --rm cargo.ayedo.cloud/library/polycrate:latest /bin/sh

Bind-Mount-Fehler auf macOS mit OrbStack (0.36.0)

Problem: Auf macOS mit OrbStack (oder anderen alternativen Docker-Runtimes) schlägt die Action-Ausführung mit einem Bind-Mount-Fehler fehl. Die Fehlermeldung enthält typischerweise den Pfad /var/run/com.apple.launchd.*/Listeners.

Error: failed to create container: ... bind mount source path does not exist:
/var/run/com.apple.launchd.XXXXX/Listeners

Ursache: Der SSH-Agent-Socket (SSH_AUTH_SOCK) wird in den Container gemountet. Auf macOS zeigt SSH_AUTH_SOCK auf einen launchd-Socket, der von OrbStack nicht in die Docker-VM durchgereicht werden kann.

Lösung (ab 0.37.0): SSH-Agent-Mount ist per Default deaktiviert. Falls Sie den Mount explizit aktiviert haben und dieses Problem auftritt, entfernen Sie die Aktivierung:

  • Entfernen Sie --ssh-agent-mount aus dem CLI-Aufruf
  • Entfernen Sie sshagentmount: true aus workspace.poly

Lösung (0.36.x): Deaktivieren Sie den SSH-Agent-Mount mit --no-ssh-agent-mount oder config.sshagentmount: false.

Action Run Submission schlägt fehl: Exit Code -1 (vor 0.36.0)

Problem: Ein Action Run wird an die Polycrate API submitted, aber die API lehnt ihn ab, weil der Exit Code -1 ist. Die API erwartet Exit Codes >= 0.

Error: exit_code: Ensure this value is greater than or equal to 0

Ursache: Vor Version 0.36.0 gaben Docker-Infrastrukturfehler (Container-Create, Attach, Start) den Exit Code -1 zurück, was ein interner Sentinel-Wert war. Die API akzeptiert nur POSIX-konforme Exit Codes (0–255).

Lösung: Update auf Polycrate CLI >= 0.36.0. Alle Infrastrukturfehler geben nun Exit Code 1 zurück:

polycrate update 0.51.3

Workspace-Probleme

"Not a valid workspace"

Problem: Polycrate erkennt das Verzeichnis nicht als Workspace.

Error: Not a valid workspace: workspace.poly not found

Lösungen:

  1. Prüfen Sie, ob workspace.poly existiert: 

    ls -la workspace.poly

  2. Initialisieren Sie einen neuen Workspace (im Zielverzeichnis): 

    mkdir -p ~/polycrate-workspaces/my-workspace
cd ~/polycrate-workspaces/my-workspace
polycrate workspace init --with-name my-workspace

  3. Geben Sie den Workspace-Pfad explizit an: 

    polycrate run my-block install --workspace /path/to/workspace

Workspace-Verschlüsselung schlägt fehl

Problem: Verschlüsselung oder Entschlüsselung des Workspace schlägt fehl.

Lösungen:

  1. Prüfen Sie den Verschlüsselungsstatus: 

    polycrate workspace status

  2. Stellen Sie sicher, dass Sie die richtige Passphrase verwenden

  3. Prüfen Sie, ob verschlüsselte Dateien existieren: 

    ls -la *.enc

  4. Backup vor Verschlüsselung erstellen: 

    cp workspace.poly workspace.poly.backup
polycrate workspace encrypt

Snapshot-Fehler

Problem: Snapshot kann nicht generiert werden.

Lösungen:

  1. Validieren Sie Ihre Workspace-Konfiguration: 

    polycrate workspace inspect

  2. Prüfen Sie auf Syntax-Fehler in workspace.poly: 

    # Verwenden Sie einen YAML-Validator
yamllint workspace.poly

  3. Testen Sie den Snapshot isoliert: 

    polycrate workspace snapshot

Block-Probleme

"Block not found"

Problem: Polycrate kann einen Block nicht finden.

Error: Block 'my-block' not found in workspace

Lösungen:

  1. Listen Sie alle verfügbaren Blocks auf: 

    polycrate block list

  2. Prüfen Sie die Block-Directory: 

    ls -la blocks/

  3. Pullen Sie den Block aus der Registry (vollständiger Pfad!): 

    polycrate blocks pull registry.my-org.com/infra/my-block:1.0.0

  4. Prüfen Sie die Block-Konfiguration: 

    cat blocks/my-block/block.poly

Block-Validation schlägt fehl

Problem: Block-Validierung schlägt fehl.

Error: Block configuration validation failed

Lösungen:

  1. Validieren Sie den Block: 

    polycrate block validate my-block

  2. Prüfen Sie die block.poly auf Syntax-Fehler: 

    yamllint blocks/my-block/block.poly

  3. Inspizieren Sie die Block-Konfiguration: 

    polycrate block inspect my-block

Block Push/Pull schlägt fehl

Problem: Block kann nicht in die Registry gepusht oder von ihr gepullt werden.

Lösungen:

  1. Authentifizieren Sie sich bei der Registry: 

    docker login cargo.ayedo.cloud
# oder für custom Registry:
docker login my.registry.com

  2. Prüfen Sie die Registry-URL (vollständiger Pfad mit Version!): 

    # Vollständiger Registry-Pfad erforderlich
polycrate blocks pull my.registry.com/my-org/my-block:1.0.0

  3. Prüfen Sie die Block-Version: 

    # In block.poly
cat blocks/my-block/block.poly | grep version

  4. Prüfen Sie Netzwerk-Verbindung zur Registry: 

    curl -I https://cargo.ayedo.cloud

Action-Probleme

"Action not found"

Problem: Action existiert nicht oder kann nicht gefunden werden.

Error: Action 'install' not found in block 'my-block'

Lösungen:

  1. Listen Sie alle verfügbaren Actions auf: 

    polycrate action list

  2. Inspizieren Sie den Block: 

    polycrate block inspect my-block

  3. Prüfen Sie die Block-Konfiguration: 

    cat blocks/my-block/block.poly

Action schlägt fehl

Problem: Action-Ausführung schlägt mit Fehler fehl.

Lösungen:

  1. Erhöhen Sie den Log-Level: 

    polycrate run my-block install --loglevel 2

  2. Prüfen Sie die Logs: 

    cat .logs/<latest-log-file>

  3. Führen Sie die Action lokal aus (für Debugging): 

    polycrate run my-block install --local

  4. Inspizieren Sie die Action: 

    polycrate action inspect my-block install

  5. Testen Sie mit Snapshot (ohne Ausführung): 

    polycrate run my-block install --snapshot

Ansible-Fehler

Problem: Ansible-Playbook schlägt fehl.

Lösungen:

  1. Prüfen Sie die Ansible-Syntax: 

    # Im Block-Verzeichnis
ansible-playbook --syntax-check install.yml

  2. Erhöhen Sie Ansible-Verbosity: 

    polycrate run my-block install --loglevel 2

  3. Prüfen Sie das Inventory: 

    cat inventory.yml
ansible-inventory -i inventory.yml --list

  4. Testen Sie Ansible-Verbindung: 

    ansible all -i inventory.yml -m ping

Workflow-Probleme

Workflow schlägt fehl

Problem: Workflow-Ausführung schlägt fehl.

Lösungen:

  1. Listen Sie alle Workflows auf: 

    polycrate workflow list

  2. Inspizieren Sie den Workflow: 

    polycrate workflow inspect my-workflow

  3. Führen Sie Steps einzeln aus: 

    # Führen Sie jeden Step einzeln aus, um den fehlerhaften Step zu finden
polycrate run step-1-block step-1-action

  4. Verwenden Sie allow_failure für optionale Steps: 

    workflows:
  - name: my-workflow
    steps:
      - name: optional-step
        block: my-block
        action: optional-action
        allow_failure: true

SSH-Probleme

SSH-Verbindung schlägt fehl

Problem: SSH-Verbindung zu Remote-Host schlägt fehl.

Error: SSH connection failed

Lösungen:

  1. Prüfen Sie SSH-Keys: 

    ls -la id_rsa id_rsa.pub
chmod 600 id_rsa
chmod 644 id_rsa.pub

  2. Testen Sie SSH-Verbindung manuell: 

    ssh -i id_rsa user@host

  3. Prüfen Sie das Inventory: 

    cat inventory.yml

  4. Verwenden Sie SSH-Passphrase ⚠️ Experimental: 

    echo "my-passphrase" > ssh-passphrase.poly
polycrate workspace encrypt
polycrate run my-block install --ssh-use-passphrase

  5. Prüfen Sie authorized_keys auf Remote-Host: 

    cat ~/.ssh/authorized_keys

Performance-Probleme

Polycrate ist langsam

Problem: Polycrate-Ausführung dauert sehr lange.

Lösungen:

  1. Überspringen Sie Image-Pull (wenn bereits vorhanden): 

    polycrate run my-block install --pull false

  2. Überspringen Sie Image-Build (wenn kein Custom Dockerfile.poly): 

    polycrate run my-block install --build false

  3. Führen Sie lokal aus (wenn möglich): 

    polycrate run my-block install --local

  4. Prüfen Sie Docker-Performance: 

    docker stats

  5. Erhöhen Sie Docker-Ressourcen (Docker Desktop): - Settings → Resources → Increase CPU/Memory

Container baut lange

Problem: Custom Container-Image braucht lange zum Bauen.

Lösungen:

  1. Optimieren Sie Ihr Dockerfile.poly: 

    # Dockerfile.poly
FROM cargo.ayedo.cloud/library/polycrate:latest

# Cache-freundliche Layer-Reihenfolge (Ubuntu-basiert!)
RUN apt-get update && apt-get install -y --no-install-recommends \
    tool1 tool2 \
    && rm -rf /var/lib/apt/lists/*

  2. Verwenden Sie Docker Build-Cache: 

    # Docker Desktop Build-Cache aktivieren

  3. Überspringen Sie Build wenn möglich: 

    polycrate run my-block install --build false

Konfigurationsprobleme

Umgebungsvariablen in YAML funktionieren nicht

Problem: ${VAR} Syntax in workspace.poly oder block.poly wird nicht aufgelöst.

# ❌ Funktioniert NICHT - YAML unterstützt keine Env-Var-Substitution
config:
  api_key: ${API_KEY}  # Bleibt literal als "${API_KEY}"

Lösung: Verwenden Sie secrets.poly für sensitive Konfiguration:

# workspace.poly - öffentliche Konfiguration
name: my-workspace

blocks:
  - name: my-app
    from: registry.my-org.com/infra/app:1.0.0
    config:
      namespace: production

# secrets.poly - sensitive Konfiguration (verschlüsselt speichern!)
blocks:
  - name: my-app
    config:
      api_key: mein-geheimer-api-key
      database_password: db-passwort

# Workspace verschlüsseln vor Git-Push
polycrate workspace encrypt

→ Workspace-Verschlüsselung

Merge-Konflikte in Konfiguration

Problem: Konfigurationen werden nicht korrekt zusammengeführt.

Lösungen:

  1. Aktivieren Sie Merge-Debugging: 

    polycrate run my-block install --merge-debug

  2. Verwenden Sie Merge v2: 

    polycrate run my-block install --merge-v2

  3. Inspizieren Sie den finalen Snapshot: 

    polycrate run my-block install --snapshot > snapshot.yml
cat snapshot.yml

Registry-Probleme

"Registry authentication failed"

Problem: Authentifizierung bei der Registry schlägt fehl.

Lösungen:

  1. Login via Docker: 

    docker login cargo.ayedo.cloud
Username: your-username
Password: your-password

  2. Prüfen Sie Docker-Config: 

    cat ~/.docker/config.json

  3. Verwenden Sie API-Key statt Passwort: 

    docker login cargo.ayedo.cloud -u your-username -p your-api-key

"Rate limit exceeded"

Problem: Zu viele Requests zur Registry.

Lösungen:

  1. Authentifizieren Sie sich (höhere Limits für authentifizierte User): 

    docker login cargo.ayedo.cloud

  2. Warten Sie und versuchen Sie es später erneut

  3. Verwenden Sie einen Mirror/Cache

Häufige Fehlermeldungen

"permission denied"

  • Prüfen Sie Datei-Berechtigungen: chmod 755 file
  • Prüfen Sie Docker-Berechtigungen: sudo usermod -aG docker $USER
  • Prüfen Sie SSH-Key-Berechtigungen: chmod 600 id_rsa

"no space left on device"

  • Prüfen Sie Speicherplatz: df -h
  • Bereinigen Sie Docker: docker system prune -a
  • Bereinigen Sie Polycrate-Logs: rm -rf .logs/*
  • Bereinigen Sie Artefakte: polycrate run my-block prune (falls der Block eine prune-Action hat)

"port already in use"

  • Prüfen Sie verwendete Ports: netstat -tuln | grep <port>
  • Stoppen Sie konfligierende Container: docker ps und docker stop <container>
  • Verwenden Sie anderen Port in der Konfiguration

"connection timeout"

  • Prüfen Sie Netzwerk-Verbindung
  • Prüfen Sie Firewall-Regeln
  • Erhöhen Sie Timeout-Werte
  • Prüfen Sie DNS-Auflösung: nslookup host

Debugging-Tipps

Erweiterte Logs

# Maximaler Log-Level
polycrate run my-block install --loglevel 2

# JSON-Format für maschinelle Verarbeitung
polycrate run my-block install --logformat json

# YAML-Format
polycrate run my-block install --logformat yaml

Interaktiver Modus

# Container bleibt offen für interaktive Befehle
polycrate run my-block install --interactive

Snapshot analysieren

# Snapshot generieren und analysieren
polycrate run my-block install --snapshot > snapshot.yml

# Prüfen auf spezifische Werte
cat snapshot.yml | grep "key_name"

# Mit yq filtern
yq eval '.blocks[].config' snapshot.yml

Container debuggen

# Shell im Container öffnen
docker run -it --rm \
  -v $(pwd):/workspace \
  cargo.ayedo.cloud/library/polycrate:latest \
  /bin/sh

# Im Container
cd /workspace
ls -la

Support

Wenn Sie das Problem nicht lösen können:

  1. Dokumentation prüfen: - CLI-Referenz - Best Practices

  2. Community fragen: - Discord Server - GitHub Discussions

  3. Issue erstellen: - GitHub Issues - Fügen Sie Logs, Konfiguration und Reproduktionsschritte hinzu

Siehe auch