DEEN

DocsReference

Troubleshooting

The usual suspects, and how to report the rest.

Alran Code reports errors with a number. Every number, what it means and what to do about it stands on Error codes.

Why do I get "alran: command 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

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

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"

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

Claude runs on your own Anthropic key: add it on the Ottili AI Platform 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

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

@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 checks the local config file, /status shows account and model, /config the effective configuration.

Report a bug

Open an issue on GitHub 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.

Common questions

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.