---
title: "Fehlerbehebung · Alran-Code-Doku"
url: https://alran.dev/de/docs/troubleshooting
locale: de
updated: 2026-11-16
---

[Doku](https://alran.dev/de/docs)Referenz

# Fehlerbehebung

Die üblichen Verdächtigen, und wie du den Rest meldest.

Auf dieser Seite

[Warum bekomme ich &quot;alran: command not found&quot;?](#not-found) [Nicht unterstütztes Node.js](#node) [Natives Modul lässt sich nicht bauen](#native) [„Login required“](#login) [byok_key_required](#credit) [Das Gateway ist nicht erreichbar](#gateway) [Ein altes Paket ist installiert](#old) [Deine Einrichtung prüfen](#doctor) [Einen Fehler melden](#report) [Häufige Fragen](#faq)Alran Code meldet Fehler mit einer Nummer. Alle Nummern, was sie bedeuten und was du dagegen tun kannst, stehen auf [Fehlercodes](https://alran.dev/de/docs/errors).

## Warum bekomme ich "alran: command not found"? {#not-found}

Öffne nach dem Installer ein neues Terminal, damit deine Shell den neuen `PATH` liest. Prüfen mit `command -v alran`. Hast du `ALRAN_NO_MODIFY_PATH` gesetzt, trag `~/.alran-code/bin` selbst in den `PATH` ein.

## Nicht unterstütztes Node.js {#node}

Alran Code braucht Node.js 22.19+ (22.x), 24.2+ (24.x), 25 oder 26. Node 24.0 und 24.1 werden nicht unterstützt. Der Installer bringt eigenes Node.js mit, wenn deins nicht passt; mit npm aktualisierst du Node.js zuerst.

## Natives Modul lässt sich nicht bauen {#native}

`better-sqlite3` braucht sein Installationsskript. Lass optionale Abhängigkeiten an; gibt es für deine Node-Version kein fertiges Binary, installier Python und C/C++-Build-Tools und installier neu.

## „Login required“ {#login}

Die Sitzung ist abgelaufen oder wurde widerrufen. Führ `alran auth login` aus. In der CI setzt du `ALRAN_API_KEY`. Konto-Befehle enden hier mit Exit-Code 2.

## byok_key_required {#credit}

Claude läuft auf deinem eigenen Anthropic-Schlüssel: Hinterlege ihn auf der [Ottili AI Platform](https://ai.ottili.one) unter Einstellungen → Anbieter-Schlüssel, oder wechsel zurück mit `alran config model werk`. `byok_key_invalid` und `byok_key_rejected` bedeuten, dass Anthropic den gespeicherten Schlüssel nicht annimmt; tausche ihn aus. `byok_provider_billing` (HTTP 402) bedeutet, dass dein Anthropic-Konto leer ist — fülle es bei Anthropic auf, nicht bei Ottili. Die Konto-Befehle enden mit Exit-Code 5.

## Das Gateway ist nicht erreichbar {#gateway}

Exit-Code 4, mit der Gateway-URL in der Meldung. Prüf Verbindung und Proxy und versuch es erneut. Alran wechselt nie von selbst den Anbieter.

## Ein altes Paket ist installiert {#old}

`@ottili/alran-code` oder `@ottili/code` aus frühen Builds werden nicht an Ort und Stelle aktualisiert. Deinstallier sie und installier `alran`:

```bash
npm uninstall -g @ottili/code @ottili/alran-code
npm install -g alran
```

## Deine Einrichtung prüfen {#doctor}

`/doctor` prüft die lokale Konfigurationsdatei, `/status` zeigt Konto und Modell, `/config` die wirksame Konfiguration.

## Einen Fehler melden {#report}

Eröffne ein Issue auf [GitHub](https://github.com/Alran-AI/code/issues/new/choose) mit `alran --version`, der Oberfläche (TUI, `exec`, ACP) und einer minimalen Reproduktion. Entfern vorher Schlüssel und private Projektinhalte. Sicherheitslücken meldest du vertraulich über GitHub: **Security → Report a vulnerability**. Mehr auf der [Sicherheitsseite](https://alran.dev/de/security).

## Häufige Fragen {#faq}

Warum bekomme ich "alran: command not found"?

Öffne nach dem Installer ein neues Terminal, damit deine Shell den neuen PATH liest, und prüfe mit command -v alran. Hast du ALRAN_NO_MODIFY_PATH gesetzt, trage ~/.alran-code/bin selbst in den PATH ein.

Welche Node.js-Version braucht Alran Code?

Alran Code braucht Node.js 22.19+ (22.x), 24.2+ (24.x), 25 oder 26, und Node 24.0 und 24.1 werden nicht unterstützt. Der Installer bringt eigenes Node.js mit, wenn deins nicht passt, und mit npm aktualisierst du Node.js zuerst.

Wie melde ich einen Fehler?

Eröffne ein Issue auf GitHub mit alran --version, der genutzten Oberfläche (TUI, exec, ACP) und einer minimalen Reproduktion, und entferne vorher Schlüssel und private Projektinhalte. Sicherheitslücken meldest du vertraulich über GitHub.

[ZurückFehlercodes](https://alran.dev/de/docs/errors)
