Zum Hauptinhalt springen
Lösungen für häufige Build-Fehler, Antworten auf häufig gestellte Fragen und eine Anleitung zur Migration von der interaktiven Legacy-Einrichtung.
Informationen zur allgemeinen Environment-Konfiguration finden Sie unter Environment Configuration. Details zur Syntax finden Sie in der YAML Reference.

​
Fehlerbehebung bei Build-Fehlschlägen

​
Schritt 1: Build-Status prüfen

Gehen Sie zu Settings > Devin’s Environment > Build History. Ihr Build zeigt einen der folgenden Status an:
StatusBedeutungWas zu tun ist
SuccessAlles hat funktioniertNichts — Ihr Maschinenabbild ist bereit
PartialDer Hauptteil des Builds war erfolgreich, aber einige Repos sind fehlgeschlagenPrüfen Sie, welche Repos fehlgeschlagen sind; deren Sitzungen haben möglicherweise Probleme
FailedDer Build selbst ist fehlgeschlagenPrüfen Sie das Build-Log des fehlgeschlagenen Schritts
CancelledEin neuerer Build hat diesen ersetztNormal — starten Sie bei Bedarf einen neueren Build
SkippedEs wurden keine Konfigurationsänderungen erkanntNichts — es war kein Build erforderlich

​
Schritt 2: Build-Logs lesen

Build-Logs sind nach Schritten gegliedert:
  1. Gemeinsames Setup — Enterprise- und org-weite Befehle
  2. Klonen — Klonen des Repositorys
  3. Repo-Setup — Befehle pro Repository
  4. Abschluss — Systemprüfung und Image-Erstellung
Achten Sie in den Logs auf den ersten Fehler. Nachfolgende Fehler sind oft Folgefehler, die durch den ersten ausgelöst werden.
Wenn Sie die Erweiterte Form mit name-Feldern verwendet haben, zeigen die Logs genau, welcher Schritt fehlgeschlagen ist. Das ist einer der größten Vorteile benannter Schritte: 
# Ohne Namen — schwer zu debuggen
initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh
  npm install -g pnpm

# Mit Namen — Fehler leicht zu erkennen
initialize:
  - name: Install uv
    run: curl -LsSf https://astral.sh/uv/install.sh | sh
  - name: Install pnpm
    run: npm install -g pnpm

​
Step 3: Fehlermuster erkennen

​
Fehler beim Klonen

Symptom: Der Build schlägt beim Klonen fehl. Häufige Ursachen:
  • Repository-Zugriff ist nicht konfiguriert — überprüfen Sie Enterprise Settings > Integrations
  • Für ein privates Repo ist ein Authentifizierungstoken erforderlich
  • Das Repository wurde umbenannt oder gelöscht
  • Problem mit der Netzwerkverbindung (VPN oder Proxy erforderlich)
Lösung: Vergewissern Sie sich, dass Devin in Ihren Integrationseinstellungen Zugriff auf das Repository hat. Stellen Sie bei privaten Registries sicher, dass die Anmeldedaten in Secrets konfiguriert sind.

​
Fehler bei der Installation von Abhängigkeiten

Symptom: Der Build schlägt während der Einrichtung des Repos fehl, meist bei npm install, pip install oder Ähnlichem. Häufige Ursachen:
  • Private Paket-Registry erfordert Authentifizierung — Token unter Secrets hinzufügen
  • Konflikt bei Paketversionen — konkrete Versionen festschreiben
  • Netzwerk-Timeout — prüfen, ob VPN erforderlich ist
  • Registry-URL falsch konfiguriert
Lösung: Fügen Sie die Registry-Authentifizierung in Ihrem Abschnitt maintenance hinzu. Beispiele für private Registry-Muster finden Sie unter Konfigurationsbeispiele.

​
Timeout-Fehler

Symptom: Der Build scheint hängen zu bleiben und schlägt dann fehl. Häufige Ursachen:
  • Eine interaktive Abfrage wartet auf Eingabe — fügen Sie -y-Flags hinzu, verwenden Sie DEBIAN_FRONTEND=noninteractive
  • Die Installation sehr großer Abhängigkeiten dauert zu lange
  • Der Befehl überschreitet das 1-Stunden-Timeout
Lösung: Fügen Sie allen Installationsbefehlen nicht interaktive Flags hinzu. Verschieben Sie langsame einmalige Installationen nach initialize, damit sie nur bei Builds ausgeführt werden (nicht in jeder Sitzung). 
# Schlecht — hängt beim Warten auf Eingabe
initialize: |
  sudo apt-get install libpq-dev

# Gut — nicht-interaktiv
initialize: |
  sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq libpq-dev

​
Berechtigungsfehler

Symptom: „Permission denied“ in den Logs. Häufige Ursachen:
  • Fehlendes sudo bei der Installation von Systempaketen
  • Es wird versucht, in geschützte Verzeichnisse zu schreiben
  • Die Datei gehört aufgrund eines vorherigen Builds einem anderen Nutzer
Lösung: Verwenden Sie sudo für Vorgänge auf Systemebene (apt-get, Schreiben nach /etc/ usw.). Bei Paketmanagern auf Nutzerebene (npm, pip, cargo) ist sudo in der Regel nicht erforderlich.

​
”Command not found”-Fehler

Symptom: Ein in initialize installiertes Tool ist in maintenance oder in späteren Schritten nicht verfügbar. Häufige Ursachen:
  • Das Tool wird in einem Verzeichnis installiert, das nicht in PATH enthalten ist
  • Änderungen am Shell-Profil (.bashrc) werden in nachfolgenden Schritten nicht eingebunden
Lösung: Fügen Sie das Verzeichnis des Tools über $ENVRC zu PATH hinzu: 
initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh
  echo 'export PATH="$HOME/.local/bin:$PATH"' >> $ENVRC

​
Schritt 4: Iterieren

Nachdem Sie das Problem identifiziert haben:
  1. Korrigieren Sie Ihre YAML-Konfiguration
  2. Speichern Sie — ein neuer Build wird automatisch gestartet
  3. Prüfen Sie das Build-Log des neuen Builds
Testen Sie Befehle zuerst. Bevor Sie Ihrer Konfiguration einen Befehl hinzufügen, führen Sie ihn am besten in einer Devin-Sitzung aus, um sicherzustellen, dass er funktioniert. Das geht schneller, als auf einen vollständigen Build-Zyklus zu warten.

​
Kurzreferenz zu häufigen Fehlern

FehlerWahrscheinliche UrsacheBehebung
command not foundTool nicht installiert oder nicht im PATHZu initialize hinzufügen oder über $ENVRC zum PATH hinzufügen
Permission deniedFehlendes sudoFür Systempakete sudo apt-get install verwenden
npm ERR! 404Privates Paket, keine AuthentifizierungRegistry-Auth-Token in maintenance hinzufügen (Beispiele)
E: Unable to locate packageapt-get update wurde nicht zuerst ausgeführtsudo apt-get update -qq vor apt-get install hinzufügen
ZeitüberschreitungLangsame Installation oder interaktive EingabeaufforderungNach initialize verschieben; -y und DEBIAN_FRONTEND=noninteractive hinzufügen
Leere Konfigurationsdateien nach dem SitzungsstartZugangsdaten wurden in initialize geschriebenSchritte für Zugangsdaten nach maintenance verschieben
Build erfolgreich, aber Sitzung ist fehlerhaftmaintenance-Befehl schlägt beim Sitzungsstart fehlTesten Sie Ihre maintenance-Befehle manuell in einer Sitzung

​
Von der interaktiven Einrichtung migrieren

Wenn Sie derzeit die ältere interaktive Legacy-Einrichtung (den Schritt-für-Schritt-Assistenten) verwenden, können Sie zu einer deklarativen Konfiguration wechseln, um eine bessere Reproduzierbarkeit und Unterstützung für mehrere Repos zu erhalten.

​
So funktioniert die Migration

Das Legacy-Setup und die deklarative Konfiguration erzeugen jeweils ein eigenes Maschinenabbild. Sitzungen verwenden entweder das eine oder das andere — niemals eine Hybridlösung. Ein Schalter auf Org-Ebene namens „Legacy-Maschinen-Snapshot verwenden“ steuert, welches Abbild verwendet wird:
  • Schalter EIN (Standard) — alle Sitzungen verwenden den Legacy-Snapshot. Keine Unterbrechung.
  • Schalter AUS — alle Sitzungen verwenden den deklarativen Snapshot.
Das bedeutet, dass du das deklarative Setup parallel konfigurieren und testen kannst, während alle anderen weiterhin mit dem Legacy-Snapshot arbeiten.

​
Migrationsschritte

1

Bereiten Sie Ihre Konfiguration vor

Notieren Sie die Befehle aus Ihrer aktuellen interaktiven Einrichtung — diese ordnen Sie anschließend den YAML-Abschnitten zu:
Schritt im Legacy-AssistentenDeklaratives Äquivalent
Git pullAutomatisch (integriert)
Secrets konfigurierenSecrets (unverändert)
Abhängigkeiten installierenAbschnitt initialize
Abhängigkeiten verwaltenAbschnitt maintenance
Lint einrichtenknowledge-Eintrag mit dem Namen lint
Tests einrichtenknowledge-Eintrag mit dem Namen test
Lokale App ausführenknowledge-Eintrag mit dem Namen startup
Zusätzliche Hinweiseknowledge-Eintrag mit dem Namen notes
2

Schreiben Sie Ihr YAML

Gehen Sie zu Settings > Devin’s Environment und wählen Sie Ihr Repository aus. Ordnen Sie dort Ihre Legacy-Befehle zu:
# Legacy-„Abhängigkeiten installieren“ → initialize
initialize: |
  nvm use 18
  npm install -g pnpm

# Legacy-„Abhängigkeiten verwalten“ → maintenance
maintenance: |
  pnpm install

# Legacy-„Lint/Tests/App/Hinweise einrichten“ → knowledge
knowledge:
  - name: lint
    contents: |
      pnpm lint
  - name: test
    contents: |
      pnpm test
  - name: startup
    contents: |
      pnpm dev (port 3000)
  - name: notes
    contents: |
      Führen Sie vor jedem Commit immer Lint aus.
Oder starten Sie einfach eine Devin-Sitzung und bitten Sie Devin, das Repo einzurichten — Devin kann die Konfiguration automatisch für Sie generieren.
3

Speichern und auf den Build warten

Speichern Sie Ihre Konfiguration. Ein Build startet automatisch. Verfolgen Sie den Fortschritt unter Build History. Builds sind kostenlos — sie verbrauchen keine ACUs.
4

Vor dem Umstellen testen

Bevor Sie für alle umstellen, testen Sie das deklarative Setup in einzelnen Sitzungen mit der manuellen Übersteuerung. So können Sie (oder die Person, die an der Konfiguration arbeitet) den deklarativen Snapshot verwenden, während alle anderen beim Legacy-Snapshot bleiben.Passen Sie die Konfiguration iterativ an, bis das deklarative Setup Ihre Legacy-Umgebung vollständig abbildet.
5

Umstellen

Sobald Sie sicher sind, setzen Sie in den Settings Ihrer org OFF für „Use legacy machine snapshot“. Alle neuen Sitzungen verwenden dann den deklarativen Snapshot.
Interaktive Authentifizierungsabläufe (z. B. AWS-SSO-Browser-Login oder OAuth-Abläufe, die einen Browser erfordern) können im deklarativen Format nicht nachgebildet werden. Wenn Ihr Legacy-Setup browserbasierte Authentifizierung verwendet, müssen Sie diese Abläufe vor der Migration auf Headless-Alternativen (API-Schlüssel, Servicekonto-Token usw.) umstellen. Fügen Sie Anmeldedaten zu Secrets hinzu und verweisen Sie im Abschnitt maintenance darauf.

​
Enterprise-Migration

Für Unternehmen mit mehreren Organisationen:
  1. Konfigurieren Sie zuerst die YAML auf Unternehmensebene — gemeinsam genutzte Infrastruktur wie VPN, Zertifikate und Proxy-Einstellungen.
  2. Migrieren Sie jeweils nur eine Organisation. Jede Organisation hat ihren eigenen Legacy-Schalter, sodass Sie die Migration schrittweise durchführen können, ohne andere Teams zu beeinträchtigen.
  3. Ziehen Sie eine Testorganisation in Betracht. Erstellen Sie für große Unternehmen eine dedizierte Testorganisation, um die deklarative Konfiguration zu überprüfen, bevor Sie sie in Produktionsorganisationen ausrollen.
  4. Nutzen Sie Devin für die Skalierung. Devin kann Repos über parallele Sitzungen konfigurieren — starten Sie eine Sitzung pro Repo, und Devin erstellt automatisch Konfigurationsvorschläge. Das eignet sich gut für das Onboarding von 10 bis über 100 Repos.

​
Was passiert mit meinem alten Snapshot?

Ihr alter Snapshot bleibt erhalten. Wenn der neue deklarative Build fehlschlägt, greift Devin auf den zuletzt erfolgreichen Snapshot zurück (möglicherweise Ihren Legacy-Snapshot). Frühere Snapshots können Sie auch über den Build-Verlauf wiederherstellen.

​
Wesentliche Unterschiede

MerkmalLegacy (interaktiv)Deklarativ (YAML)
ReproduzierbarkeitZustandsbehaftet — Snapshots sammeln Änderungen im Laufe der Zeit anVollständig aus YAML reproduzierbar
Mehrere ReposImmer nur ein Repo gleichzeitigMehrere Repos in einem Build mit gleichzeitigem Klonen
WartungManuelle Schritte zum „Pflegen von Abhängigkeiten“Automatisch — maintenance wird zu Sitzungsbeginn ausgeführt
Enterprise-/Org-EbenenNicht unterstützt3-stufige Hierarchie (Enterprise → Org → Repo)
Devin-VorschlägeNur im AssistentenIn der Sitzung — Devin kann Konfigurationsänderungen vorschlagen
KostenAssistenten-Sitzungen verbrauchten ACUsSetup-Sitzungen ~1–3 ACUs; Builds sind kostenlos

​
Häufig gestellte Fragen

​
Allgemein

Was passiert, wenn ich eine Sitzung in einem Repo ausführe, das nicht eingerichtet ist? Devin funktioniert trotzdem — muss Ihr Projekt dann aber jedes Mal von Grund auf neu erfassen. Das bedeutet, Zeit für die Installation von Abhängigkeiten aufzuwenden, herauszufinden, wie das Projekt gebaut und getestet wird, und Konventionen zu erraten. Sitzungen dauern dadurch länger und kosten mehr ACUs. Wenn Sie Ihre Umgebung einrichten, startet Devin jede Sitzung vorkonfiguriert und sofort einsatzbereit. Wie lange dauert ein Build? In der Regel 5–15 Minuten, abhängig von der Anzahl der Repos und der Größe der Abhängigkeiten. Builds haben nach 2 Stunden ein Timeout. Wie viel kostet das? Builds sind kostenlos — sie kosten keine ACUs. Wenn Sie eine Devin-Sitzung verwenden, um ein Repo einzurichten (z. B. indem Sie Devin bitten, Ihre Konfiguration zu generieren), kostet diese Sitzung in der Regel 1–3 ACUs. Sobald die Konfiguration gespeichert ist, sind alle daraus folgenden Builds kostenlos. Kann ich sowohl das Legacy- als auch das deklarative Setup verwenden? Eine Organisation verwendet immer nur einen Modus, gesteuert über den Schalter „Use legacy machine snapshot“. Sie können das deklarative Setup parallel konfigurieren, während der Schalter noch aktiviert ist (Legacy-Modus), und dann wechseln, wenn Sie so weit sind. Weitere Informationen finden Sie in der Migrationsanleitung. Kann ich das deklarative Setup testen, ohne andere Nutzer zu beeinträchtigen? Ja. Verwenden Sie bei einzelnen Sitzungen die manuelle Übersteuerung, um vorübergehend den deklarativen Snapshot zu nutzen, während alle anderen beim Legacy-Snapshot bleiben. In Enterprise können Sie außerdem eine dedizierte Testorganisation erstellen. Was passiert, wenn mein Build fehlschlägt? Devin verwendet den zuletzt erfolgreichen Snapshot. Ein fehlgeschlagener Build beeinträchtigt bestehende Sitzungen nicht. Wann sollte ich initialize statt maintenance verwenden? Verwenden Sie initialize für einmalige Tool-Installationen (apt-get install, Einrichtung der Sprachlaufzeit, globale CLI-Tools). Verwenden Sie maintenance für die Installation von Abhängigkeiten, die aktuell bleiben müssen (npm install, pip install, uv sync). Wie füge ich Umgebungsvariablen hinzu? Schreiben Sie sie in $ENVRC: 
initialize: |
  echo "MY_VAR=value" >> $ENVRC
Kann ich Systempakete installieren? Ja, verwenden Sie in Ihrem initialize-Abschnitt sudo apt-get install. Verwenden Sie immer DEBIAN_FRONTEND=noninteractive und das Flag -y, um interaktive Abfragen zu vermeiden. Was ist, wenn ich für verschiedene Repos unterschiedliche Node-Versionen brauche? Verwenden Sie nvm in Ihrer Repo-Konfiguration: 
initialize: |
  nvm install 18
  nvm use 18
Werden interaktive Authentifizierungsabläufe unterstützt? Nein. Browserbasierte Authentifizierung (z. B. AWS-SSO-Anmeldungen oder OAuth-Abläufe, die ein Browserfenster erfordern) lässt sich im deklarativen Format nicht abbilden. Stellen Sie stattdessen auf Headless-Alternativen um — verwenden Sie API-Keys, Servicekonto-Tokens oder andere auf Anmeldedaten basierende Verfahren und speichern Sie sie in Secrets. Derzeit gibt es keinen Workaround für Workflows, die zwingend browserbasiertes SSO erfordern. Diese Repos sollten bis zur Verfügbarkeit von Headless-Alternativen weiterhin die interaktive Einrichtung verwenden.

​
Build-spezifisch

Was bedeutet „teilweiser Erfolg“? Der Kern-Build (Enterprise + org-Setup + Klonen) war erfolgreich, aber ein oder mehrere Einrichtungsschritte auf Repo-Ebene sind fehlgeschlagen. Sitzungen funktionieren, aber in den fehlgeschlagenen Repos sind die Abhängigkeiten möglicherweise nicht korrekt installiert. Warum wurde mein Build abgebrochen? Ein neuerer Build wurde ausgelöst, bevor Ihr Build abgeschlossen war. Nur der neueste Build wird ausgeführt; ältere Builds in der Warteschlange werden automatisch abgebrochen. Wird bei einer Änderung der Konfiguration eines Repos alles neu erstellt? Ja — ein Build erstellt ein einzelnes Maschinenabbild, das alle konfigurierten Repos enthält. Jede Änderung an einer beliebigen Konfiguration löst eine vollständige Neuerstellung aus. Kann ich zu einem vorherigen Build zurückkehren? Ja, über die Build History in den Environment Settings. Sie können jeden zuvor erfolgreichen Snapshot wiederherstellen. Wie viele Repos kann ich einbinden? Während eines Builds werden bis zu 10 Repos gleichzeitig geklont. Es gibt keine feste Obergrenze für die Gesamtzahl der Repos, aber mehr Repos bedeuten längere Build-Zeiten. Devin kann Repos in großem Umfang über parallele Sitzungen konfigurieren — starten Sie eine Sitzung pro Repo für 10–100+ Repos.

​
Enterprise-spezifisch

Wer kann Konfigurationen auf Enterprise-Ebene bearbeiten? Nur Enterprise-Admins. Org-Admins können org-weite Konfigurationen und Konfigurationen auf Repo-Ebene bearbeiten. Reguläre Mitglieder können Konfigurationen auf Repo-Ebene bearbeiten, wenn sie über die Berechtigung ManageOrgSnapshots verfügen. Die vollständige Berechtigungstabelle finden Sie unter Enterprise Environment Setup. Werden durch Änderungen an der Enterprise-Konfiguration alle Orgs neu erstellt? Ja. Eine Änderung auf Enterprise-Ebene löst Builds für jede Organisation im Enterprise aus. Können verschiedene Orgs unterschiedliche Konfigurationen haben? Ja. Jede Org hat ihre eigene org-weite Konfiguration und Konfigurationen auf Repo-Ebene. Die Enterprise-Konfiguration wird gemeinsam genutzt und ist additiv — sie wird vor der Konfiguration jeder Org ausgeführt. Können Konfigurationen auf niedrigeren Ebenen Konfigurationen auf höheren Ebenen überschreiben? Nein. Die Hierarchie (Enterprise → Org → Repo) ist streng additiv. Die Befehle jeder Ebene werden der Reihe nach ausgeführt, nachdem die vorherige Ebene abgeschlossen ist. Niedrigere Ebenen können nicht verhindern oder ändern, was höhere Ebenen konfigurieren. Kann eine Konfiguration auf Enterprise-Ebene Repository klonen? Nein. Das Klonen von Repository erfordert Zugriff auf Org-Ebene. Die Konfiguration auf Enterprise-Ebene kann gemeinsam genutzte Tools und Infrastruktur installieren, aber das Klonen von Repos muss auf Org- oder Repo-Ebene konfiguriert werden.

​
Bekannte Einschränkungen

  • Keine Build-Vorschau/Sandbox — jede Konfigurationsänderung löst einen vollständigen Build aus. Testen Sie Befehle zuerst in einer Sitzung.
  • Serielle Einrichtung von Repos — das Setup auf Repository-Ebene erfolgt jeweils für ein Repo nach dem anderen (in alphabetischer Reihenfolge). Viele Repos führen zu längeren Builds.
  • Keine bedingte Logik in YAML — das Format unterstützt kein if/else. Verwenden Sie bei Bedarf Shell-Bedingungen in Ihren Befehlen (z. B. [ -f package.json ] && npm install).
  • Keine Suche in Build-Logs — Build-Logs müssen manuell durchscrollt werden. Verwenden Sie benannte Schritte, damit sich Fehler leichter finden lassen.

​
Nächste Schritte