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.
| Code | Name | Was passiert ist | Was du tun kannst |
|---|---|---|---|
1 | INVALID_REQUEST | Die Anfrage war fehlerhaft und wurde abgewiesen, bevor sie lief | Anfrage korrigieren; Code melden, wenn es wiederholt auftritt |
2 | NOT_FOUND | Die Sitzung, der Agent oder die Datei existiert nicht | Id prüfen, Ressource neu anlegen oder auswählen |
3 | PERMISSION_DENIED | Dein Konto darf auf diese Ressource nicht zugreifen | Konto, Unternehmen oder Projekt mit der passenden Freigabe nutzen |
4 | CONFLICT | Die Änderung kollidiert mit etwas, das es schon gibt | Umbenennen oder den Konflikt entfernen, dann erneut senden |
5 | TIMEOUT | Der Vorgang hat die Zeit überschritten | Erneut senden oder --timeout erhöhen |
6 | ABORTED | Der Lauf wurde abgebrochen | Erneut senden, wenn der Abbruch nicht beabsichtigt war |
7 | RUNTIME_UNAVAILABLE | Die Laufzeitumgebung war nicht erreichbar | Verbindung und Proxy prüfen, dann erneut senden |
8 | INTERNAL | Ein nicht eingeordneter interner Fehler | Erneut senden; Code melden, wenn er wiederkehrt |
42212 | USAGE_LIMIT_EXCEEDED | Dein Konto hat sein Nutzungslimit erreicht | /usage prüfen, Guthaben aufladen oder Anbieter wechseln, dann erneut senden |
50001 | INTERNAL_ERROR | Ein allgemeiner interner Fehler — der Ersatz, wenn die Laufzeitumgebung keinen anderen Code liefert | /retry ausführen; Code melden, wenn er wiederkehrt |
50110 | LLM_CREDITS_EXHAUSTED | Der Anbieter meldet ein leeres Guthaben (HTTP 402) | Guthaben aufladen oder ein anderes Modell nehmen |
50111 | LLM_RATE_LIMITED | Der Anbieter drosselt Anfragen (HTTP 429) | Einen Moment warten, dann /retry ausführen |
50112 | LLM_AUTH_ERROR | Anbieter oder Gateway haben deine Zugangsdaten abgewiesen (HTTP 401/403) | alran auth login ausführen, oder API-Schlüssel und Endpunkt deines eigenen Anbieters korrigieren |
50113 | LLM_UPSTREAM_ERROR | Der Anbieter hat mit einem Fehler geantwortet | /retry ausführen; wenn es wiederholt auftritt, Anbietereinstellungen und Proxy prüfen |
50114 | LLM_MIGRATION_ERROR | Das Modell wird nicht mehr ausgeliefert | Einen Moment warten und erneut senden, oder mit alran config model das Modell wechseln |
50150 | LLM_TPM_RATE_LIMITED | Deine Tokens pro Minute sind aufgebraucht | Warten, bis das Fenster zurückgesetzt ist, dann /retry ausführen |
50151 | LLM_CLUSTER_OVERLOADED | Der Anbieter-Cluster ist überlastet (HTTP 529) | /retry ausführen oder Modell wechseln |
50200 | SAFETY_UNAVAILABLE | Der Content-Safety-Dienst war nicht erreichbar | Später erneut senden; wenn es wiederholt auftritt, Safety-Pfad und Proxy prüfen |
50201 | SAFETY_SENSITIVE | Content Safety hat die Nachricht blockiert | Nachricht überarbeiten, bevor du sie erneut sendest |
60001 | CORRUPTED_THINKING | Der 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.
| Zahl | Code der Laufzeitumgebung | Exit-Code von alran exec | Exit-Code der Konto-Befehle |
|---|---|---|---|
1 | INVALID_REQUEST | — | Platform oder Gateway haben die Anfrage abgewiesen |
2 | NOT_FOUND | Die Kommandozeile war falsch | Anmeldung nötig |
3 | PERMISSION_DENIED | Die Konfiguration ist kaputt | Das Konto ist gedrosselt |
4 | CONFLICT | Modell oder Laufzeitumgebung schlugen fehl | Die Platform ist nicht erreichbar |
5 | TIMEOUT | — | Das Guthaben deckt es nicht |
6 | ABORTED | Der Lauf hat --timeout erreicht | — |
7 | RUNTIME_UNAVAILABLE | Der Lauf hat --max-steps erreicht | — |
8 | INTERNAL | — | — |
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 Anbieters | Wird zu | Bedeutung |
|---|---|---|
1400010161 | 50110 | Das Guthaben deckt die Anfrage nicht |
2056 | 42212 | Das Nutzungslimit ist erreicht |
2067 | 42212 | Das Token-Plan-Limit ist erreicht und automatische Guthabennutzung ist aus — automatische Guthabennutzung wieder einschalten oder den Plan erhöhen |
2045, 2046, 2047, 1039, 1041 | 50150 | Der 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.
| Code | Bedeutung | Was du tun kannst |
|---|---|---|
0 | Der Lauf war erfolgreich | Nichts |
2 | Die Kommandozeile war falsch: fehlender Prompt, unbekanntes Flag oder unbrauchbares Modell | Kommandozeile korrigieren |
3 | Die Konfiguration ist kaputt | Alran öffnen und /doctor ausführen |
4 | Der Lauf startete, aber Modell oder Laufzeitumgebung schlugen fehl | Das error-Objekt der JSON-Ausgabe unten lesen: die message sagt, was schiefging, der code benennt den Fehler |
6 | Der Lauf hat --timeout erreicht | --timeout erhöhen oder die Aufgabe kleiner machen |
7 | Der Lauf hat --max-steps erreicht | --max-steps erhöhen oder die Aufgabe eingrenzen |
70 | Ein interner Fehler | Mit alran --version melden |
130 | Der Lauf wurde abgebrochen | Nichts, du hast ihn gestoppt |
141 | Die Ausgabe-Pipe wurde vorzeitig geschlossen, zum Beispiel von head | Die 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:
| Code | Bedeutung | Was du tun kannst |
|---|---|---|
0 | Der Befehl war erfolgreich | Nichts |
1 | Platform oder Gateway haben die Anfrage abgewiesen | Meldung lesen, dann Konto und Modell prüfen |
2 | Anmeldung nötig | alran auth login ausführen oder ALRAN_API_KEY setzen |
3 | Das Konto ist gedrosselt | So lange warten, wie die Meldung sagt |
4 | Platform oder Gateway waren nicht erreichbar | Verbindung und Proxy prüfen, dann erneut versuchen |
5 | Dein Guthaben deckt die Anfrage nicht, oder Claude hat keinen funktionierenden Anthropic-Schlüssel | Guthaben 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:
{
"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:
| Name | Was er bedeutet |
|---|---|
REVIEW_RESULT_MISSING | Die Laufzeitumgebung endete ohne Code-Review-Ergebnis |
REVIEW_RESULT_INVALID | Die Laufzeitumgebung lieferte ein ungültiges Code-Review-Ergebnis |
INTERACTION_NOT_AVAILABLE | Die Laufzeitumgebung hat eine Frage gestellt, und alran exec kann nicht fragen |
STRUCTURED_OUTPUT_INVALID | Die Antwort passte nicht zum verlangten Format |
RUNTIME_SHUTDOWN_FAILED | Die Laufzeitumgebung wurde nicht sauber beendet |
OUTPUT_LAST_MESSAGE_WRITE_FAILED | Die 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
| Symptom | Erster 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 scheitert | die Exit-Code-Tabelle von alran exec oben, dann das error-Objekt der JSON-Ausgabe |
| Etwas wird nicht gefunden | Ids 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.