---
title: "Troubleshooting · Alran Code Docs"
url: https://alran.dev/en/docs/troubleshooting
locale: en
updated: 2026-11-16
---

[Docs](https://alran.dev/en/docs)Reference

# Troubleshooting

The usual suspects, and how to report the rest.

On this page

[Why do I get &quot;alran: command not found&quot;?](#not-found) [Unsupported Node.js](#node) [Native module fails to build](#native) [&quot;Login required&quot;](#login) [byok_key_required](#credit) [The gateway can't be reached](#gateway) [An old package is installed](#old) [Check your setup](#doctor) [Report a bug](#report) [Common questions](#faq)Alran Code reports errors with a number. Every number, what it means and what to do about it stands on [Error codes](https://alran.dev/en/docs/errors).

## Why do I get "alran: command not found"? {#not-found}

After the installer, open a new terminal so your shell reads the new `PATH`. Check with `command -v alran`. If you set `ALRAN_NO_MODIFY_PATH`, add `~/.alran-code/bin` to your `PATH` yourself.

## Unsupported Node.js {#node}

Alran Code needs Node.js 22.19+ (22.x), 24.2+ (24.x), 25 or 26. Node 24.0 and 24.1 are not supported. The installer brings its own Node.js when yours doesn't fit; with npm, update Node.js first.

## Native module fails to build {#native}

`better-sqlite3` needs its install script. Keep optional dependencies enabled; without a prebuilt binary for your Node version, install Python and C/C++ build tools, then reinstall.

## "Login required" {#login}

The session expired or was revoked. Run `alran auth login`. In CI, set `ALRAN_API_KEY`. Account commands exit with code 2 here.

## byok_key_required {#credit}

Claude runs on your own Anthropic key: add it on the [Ottili AI Platform](https://ai.ottili.one) under Settings → Provider keys, or switch back with `alran config model werk`. `byok_key_invalid` and `byok_key_rejected` mean Anthropic does not accept the stored key; replace it. `byok_provider_billing` (HTTP 402) means your Anthropic account has no credit left — add it with Anthropic, not with Ottili. The account commands end with exit code 5.

## The gateway can't be reached {#gateway}

Exit code 4, with the gateway URL in the message. Check your connection and proxy, then retry. Alran never switches providers on its own.

## An old package is installed {#old}

`@ottili/alran-code` or `@ottili/code` from early builds are not updated in place. Uninstall them and install `alran`:

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

## Check your setup {#doctor}

`/doctor` checks the local config file, `/status` shows account and model, `/config` the effective configuration.

## Report a bug {#report}

Open an issue on [GitHub](https://github.com/Alran-AI/code/issues/new/choose) with `alran --version`, the interface (TUI, `exec`, ACP) and a minimal reproduction. Remove keys and private project content first. Security issues go privately through GitHub: **Security → Report a vulnerability**. More on the [security page](https://alran.dev/en/security).

## Common questions {#faq}

Why do I get "alran: command not found"?

After the installer, open a new terminal so your shell reads the new PATH, and check with command -v alran. If you set ALRAN_NO_MODIFY_PATH, add ~/.alran-code/bin to your PATH yourself.

Which Node.js version does Alran Code need?

Alran Code needs Node.js 22.19+ (22.x), 24.2+ (24.x), 25 or 26, and Node 24.0 and 24.1 are not supported. The installer brings its own Node.js when yours does not fit, and with npm you update Node.js first.

How do I report a bug?

Open an issue on GitHub with alran --version, the interface you used (TUI, exec, ACP) and a minimal reproduction, and remove keys and private project content first. Security issues go privately through GitHub.

[PreviousError codes](https://alran.dev/en/docs/errors)
