DEEN

DokuReferenz

Fehlercodes

Jeder Fehler, den das Terminal zeigt, trägt eine Nummer. Das ist, was jede bedeutet und was du dagegen tun kannst.

Was bedeuten die Fehlercodes des Laufs?

Wenn eine Antwort scheitert, zeigt das Fehler-Panel der Terminal-Oberfläche den Grund und eine Zeile Code: <n>. Diese Zahl ist der Code der Laufzeitumgebung. Dein Prompt bleibt erhalten, du kannst ihn also erneut senden, sobald die Ursache weg ist.

CodeNameWas passiert istWas du tun kannst
1INVALID_REQUESTDie Anfrage war fehlerhaft und wurde abgewiesen, bevor sie liefAnfrage korrigieren; Code melden, wenn es wiederholt auftritt
2NOT_FOUNDDie Sitzung, der Agent oder die Datei existiert nichtId prüfen, Ressource neu anlegen oder auswählen
3PERMISSION_DENIEDDein Konto darf auf diese Ressource nicht zugreifenKonto, Unternehmen oder Projekt mit der passenden Freigabe nutzen
4CONFLICTDie Änderung kollidiert mit etwas, das es schon gibtUmbenennen oder den Konflikt entfernen, dann erneut senden
5TIMEOUTDer Vorgang hat die Zeit überschrittenErneut senden oder --timeout erhöhen
6ABORTEDDer Lauf wurde abgebrochenErneut senden, wenn der Abbruch nicht beabsichtigt war
7RUNTIME_UNAVAILABLEDie Laufzeitumgebung war nicht erreichbarVerbindung und Proxy prüfen, dann erneut senden
8INTERNALEin nicht eingeordneter interner FehlerErneut senden; Code melden, wenn er wiederkehrt
42212USAGE_LIMIT_EXCEEDEDDein Konto hat sein Nutzungslimit erreicht/usage prüfen, Guthaben aufladen oder Anbieter wechseln, dann erneut senden
50001INTERNAL_ERROREin allgemeiner interner Fehler — der Ersatz, wenn die Laufzeitumgebung keinen anderen Code liefert/retry ausführen; Code melden, wenn er wiederkehrt
50110LLM_CREDITS_EXHAUSTEDDer Anbieter meldet ein leeres Guthaben (HTTP 402)Guthaben aufladen oder ein anderes Modell nehmen
50111LLM_RATE_LIMITEDDer Anbieter drosselt Anfragen (HTTP 429)Einen Moment warten, dann /retry ausführen
50112LLM_AUTH_ERRORAnbieter oder Gateway haben deine Zugangsdaten abgewiesen (HTTP 401/403)alran auth login ausführen, oder API-Schlüssel und Endpunkt deines eigenen Anbieters korrigieren
50113LLM_UPSTREAM_ERRORDer Anbieter hat mit einem Fehler geantwortet/retry ausführen; wenn es wiederholt auftritt, Anbietereinstellungen und Proxy prüfen
50114LLM_MIGRATION_ERRORDas Modell wird nicht mehr ausgeliefertEinen Moment warten und erneut senden, oder mit alran config model das Modell wechseln
50150LLM_TPM_RATE_LIMITEDDeine Tokens pro Minute sind aufgebrauchtWarten, bis das Fenster zurückgesetzt ist, dann /retry ausführen
50151LLM_CLUSTER_OVERLOADEDDer Anbieter-Cluster ist überlastet (HTTP 529)/retry ausführen oder Modell wechseln
50200SAFETY_UNAVAILABLEDer Content-Safety-Dienst war nicht erreichbarSpäter erneut senden; wenn es wiederholt auftritt, Safety-Pfad und Proxy prüfen
50201SAFETY_SENSITIVEContent Safety hat die Nachricht blockiertNachricht überarbeiten, bevor du sie erneut sendest
60001CORRUPTED_THINKINGDer Denkstrom des Modells kam beschädigt an/retry ausführen; Code melden, wenn er wiederkehrt

Die Codes 1 bis 8 und 50001 sind generisch. Alle anderen benennen den Teil, der gescheitert ist: das Limit, den Anbieter, die Sicherheitsprüfung oder das Modell selbst. Ab 42212 nennt die Zahl den Bereich: 42212 das Nutzungslimit, 501xx den Anbieter, 502xx die Sicherheitsprüfung, 60001 das Modell.

Dieselbe Zahl, verschiedene Bedeutungen

Eine Zahl kann in drei Tabellen dieser Seite auftauchen, und sie bedeutet nicht überall dasselbe. 2 ist eine fehlende Sitzung in der Tabelle der Fehlercodes des Laufs, eine kaputte Kommandozeile in alran exec und eine fehlende Anmeldung in einem Konto-Befehl; die Tabelle im Abschnitt „Dieselbe Zahl, verschiedene Bedeutungen“ stellt alle drei nebeneinander.

ZahlCode der LaufzeitumgebungExit-Code von alran execExit-Code der Konto-Befehle
1INVALID_REQUEST—Platform oder Gateway haben die Anfrage abgewiesen
2NOT_FOUNDDie Kommandozeile war falschAnmeldung nötig
3PERMISSION_DENIEDDie Konfiguration ist kaputtDas Konto ist gedrosselt
4CONFLICTModell oder Laufzeitumgebung schlugen fehlDie Platform ist nicht erreichbar
5TIMEOUT—Das Guthaben deckt es nicht
6ABORTEDDer Lauf hat --timeout erreicht—
7RUNTIME_UNAVAILABLEDer Lauf hat --max-steps erreicht—
8INTERNAL——

Die Exit-Codes 70, 130 und 141 gehören nur zu alran exec.

Schau eine Zahl in der Tabelle nach, zu der Stelle gehört, an der du sie gesehen hast: im Fehler-Panel der Terminal-Oberfläche ist sie ein Code der Laufzeitumgebung, im Prozessstatus ein Exit-Code.

Umgekehrt kann ein Ereignis zwei Zahlen haben: ein Timeout ist Code 5 der Laufzeitumgebung und Exit-Code 6, ein Abbruch ist Code 6 und Exit-Code 130.

Woher die Zahlen kommen

Drei Parteien sind im Spiel. Dein Konto und dein Guthaben liegen auf der Ottili AI Platform. Das Gateway leitet die Anfrage weiter und prüft bei Werk das Guthaben; bei Claude schickt es sie mit deinem eigenen Anthropic-Schlüssel weiter. Der Anbieter ist der Modellhersteller dahinter — Ottili Werk, Claude oder der, den du selbst mitgebracht hast (eigener Anbieter).

Anbieter und Gateway melden eigene Codes. Alran Code bildet sie auf die Zahlen oben ab, damit die Tabelle gleich bleibt, egal welcher Anbieter dahintersteht.

Code des AnbietersWird zuBedeutung
140001016150110Das Guthaben deckt die Anfrage nicht
205642212Das Nutzungslimit ist erreicht
206742212Das Token-Plan-Limit ist erreicht und automatische Guthabennutzung ist aus — automatische Guthabennutzung wieder einschalten oder den Plan erhöhen
2045, 2046, 2047, 1039, 104150150Der Anbieter drosselt Tokens pro Minute

Wenn einer davon in einem Log auftaucht, schau die Zahl nach, auf die er abgebildet wird.

Exit-Codes von alran exec

alran exec endet mit einer Zahl, an der dein Skript verzweigen kann. Exit-Code 4 ist ein Sammelcode: er fasst jeden Fehler von Modell oder Laufzeitumgebung zusammen, und die message der JSON-Ausgabe sagt, welcher es war.

CodeBedeutungWas du tun kannst
0Der Lauf war erfolgreichNichts
2Die Kommandozeile war falsch: fehlender Prompt, unbekanntes Flag oder unbrauchbares ModellKommandozeile korrigieren
3Die Konfiguration ist kaputtAlran öffnen und /doctor ausführen
4Der Lauf startete, aber Modell oder Laufzeitumgebung schlugen fehlDas error-Objekt der JSON-Ausgabe unten lesen: die message sagt, was schiefging, der code benennt den Fehler
6Der Lauf hat --timeout erreicht--timeout erhöhen oder die Aufgabe kleiner machen
7Der Lauf hat --max-steps erreicht--max-steps erhöhen oder die Aufgabe eingrenzen
70Ein interner FehlerMit alran --version melden
130Der Lauf wurde abgebrochenNichts, du hast ihn gestoppt
141Die Ausgabe-Pipe wurde vorzeitig geschlossen, zum Beispiel von headDie Ausgabe auslaufen lassen oder in eine Datei schreiben

Die Codes 1 und 5 kommen hier nicht vor.

Exit-Codes der Konto-Befehle

alran auth, alran config, alran models, alran usage und alran billing nutzen einen anderen Satz:

CodeBedeutungWas du tun kannst
0Der Befehl war erfolgreichNichts
1Platform oder Gateway haben die Anfrage abgewiesenMeldung lesen, dann Konto und Modell prüfen
2Anmeldung nötigalran auth login ausführen oder ALRAN_API_KEY setzen
3Das Konto ist gedrosseltSo lange warten, wie die Meldung sagt
4Platform oder Gateway waren nicht erreichbarVerbindung und Proxy prüfen, dann erneut versuchen
5Dein Guthaben deckt die Anfrage nicht, oder Claude hat keinen funktionierenden Anthropic-SchlüsselGuthaben aufladen oder Anthropic-Schlüssel hinterlegen, auf der Ottili AI Platform

Die beiden Sätze teilen sich die Zahlen 0, 2, 3 und 4, meinen aber verschiedene Dinge. 2 ist in alran exec eine kaputte Kommandozeile und in einem Konto-Befehl eine fehlende Anmeldung. Verzweige nach dem ausgeführten Befehl, nie nach der Zahl allein.

Maschinenlesbare Ausgabe

alran exec --output-format json gibt ein JSON-Dokument aus. Scheitert der Lauf, trägt es ein error-Objekt:

json
{
  "schemaVersion": 1,
  "type": "exec.result",
  "status": "failed",
  "error": {
    "category": "runtime",
    "code": "REVIEW_RESULT_MISSING",
    "message": "Runtime completed without a validated code review result.",
    "retryable": true
  },
  "durationMs": 1234
}

Das category sagt, was für eine Art von Fehler es war (config, runtime, internal), und retryable, ob ein erneutes Senden helfen kann. Der Exit-Code des Prozesses folgt trotzdem der Tabelle im Abschnitt „Exit-Codes von alran exec“.

Der code in dieser Ausgabe ist ein Name, keine Zahl, und er ist optional. Die Namen, die der Runner selbst benutzt:

NameWas er bedeutet
REVIEW_RESULT_MISSINGDie Laufzeitumgebung endete ohne Code-Review-Ergebnis
REVIEW_RESULT_INVALIDDie Laufzeitumgebung lieferte ein ungültiges Code-Review-Ergebnis
INTERACTION_NOT_AVAILABLEDie Laufzeitumgebung hat eine Frage gestellt, und alran exec kann nicht fragen
STRUCTURED_OUTPUT_INVALIDDie Antwort passte nicht zum verlangten Format
RUNTIME_SHUTDOWN_FAILEDDie Laufzeitumgebung wurde nicht sauber beendet
OUTPUT_LAST_MESSAGE_WRITE_FAILEDDie letzte Nachricht konnte nicht auf die Platte geschrieben werden

Ein fehlgeschlagener Modellaufruf trägt oft gar keinen code, nur die Meldung des Anbieters. Lies die message für das, was passiert ist, und den code, um einen Fehler des Runners zu erkennen.

Die Zahlen der ersten Tabelle stehen nicht in dieser Ausgabe. Sie gehören zum Fehler-Panel der Terminal-Oberfläche. Ein Skript muss mit message und dem Namen im code arbeiten.

Führt eine Testumgebung die Terminal-Oberfläche, kann sie die Zahl trotzdem mitnehmen: ALRAN_TUI_RESULT_PATH auf eine Datei setzen, dann wird jeder Zug als eine JSON-Zeile angehängt, mit der Zahl im Feld code des Fehlers. Dort ist der code die Zahl — dasselbe Feld trägt in der JSON-Ausgabe oben einen Namen und in dieser Datei eine Zahl.

Was du zuerst prüfst

SymptomErster Schritt
Ein Modellaufruf scheitert/status für Konto und Modell, /usage für das Guthaben
Die Konfiguration sieht falsch aus/doctor
Ein Lauf in der CI scheitertdie Exit-Code-Tabelle von alran exec oben, dann das error-Objekt der JSON-Ausgabe
Etwas wird nicht gefundenIds prüfen: die Sitzungen mit alran --session durchsehen

Immer noch nicht weiter? Die Fehlerbehebung listet die üblichen Verdächtigen. Für einen Fehlerbericht braucht es dein alran --version, die genutzte Oberfläche (TUI, exec, ACP) und eine minimale Reproduktion.

Häufige Fragen

Was bedeuten die Fehlercodes des Laufs?

Wenn eine Antwort scheitert, zeigt das Fehler-Panel der Terminal-Oberfläche den Grund und eine Zeile mit der Codenummer. Die Codes 1 bis 8 und 50001 sind generisch, alle anderen benennen den Teil, der gescheitert ist: 42212 das Nutzungslimit, 501xx den Anbieter, 502xx die Sicherheitsprüfung und 60001 das Modell.

Warum bedeutet Exit-Code 2 nicht immer dasselbe?

Dieselbe Zahl taucht in drei Tabellen auf: im Fehler-Panel der Terminal-Oberfläche ist sie ein Code der Laufzeitumgebung, im Prozessstatus ein Exit-Code. Exit-Code 2 ist in alran exec eine kaputte Kommandozeile und in einem Konto-Befehl eine fehlende Anmeldung, also verzweigst du nach dem ausgeführten Befehl und nie nach der Zahl allein.

Wie bekomme ich eine maschinenlesbare Ausgabe von alran exec?

alran exec --output-format json gibt ein JSON-Dokument aus, und wenn der Lauf scheitert, trägt es ein error-Objekt mit category, code und message. Der code ist ein Name, keine Zahl, und er ist optional, während der Exit-Code des Prozesses der Exit-Code-Tabelle von alran exec folgt.