10. Troubleshooting#
Start with these three, in this order. They answer most problems.
rayu version # what is installed
rayu auth status # is a credential configured
rayu account status # plan, credits, reset dateInside a session, /info shows the running build, model, account and token
counters, /auth shows auth state, and /config prints the active
configuration.
Install and PATH problems#
rayu: command not found right after installing#
The installer adds ~/.local/bin (macOS/Linux) or %LOCALAPPDATA%\rayu\bin
(Windows) to PATH, but only for new shells. Either open a new terminal or
apply it to the current one:
export PATH="$HOME/.local/bin:$PATH"On Windows, reopen PowerShell; the user PATH is read at process start.
An older rayu still runs#
Something earlier on PATH is winning. Check:
which -a rayu # macOS / Linux
where.exe rayu # WindowsThe v3 installer renames a shadowing npm install to rayu-legacy, but a manual
install elsewhere can still be ahead of it. Remove or rename it, or move
~/.local/bin ahead on PATH.
The legacy Node CLI opens instead of v3#
If you deliberately kept the old CLI, it is rayu-legacy, not rayu. Run
rayu-legacy for the old one and rayu for v3. To upgrade fully:
rayu updatechecksum mismatch#
The download was corrupted or tampered with and nothing was installed. Retry; if it repeats, report it with the hashes printed in the error.
Authentication problems#
"Rayu authentication is required"#
You need a Rayu credential before any turn can run:
rayu login --provider rayu # browser sign-in
export RAYU_API_KEY=rayu_sk_live_... # or an API key/login says you are already signed in but requests fail#
The stored session is stale. Sign out and back in:
/logout
/loginv3 renews an expired token once automatically, so a 401 that persists means the
refresh token itself is gone. /logout clears the stale state so /login
starts fresh.
SSH or a container has no browser#
rayu login --provider rayu --no-browserThat prints a URL and a QR code instead of opening a browser. For fully scripted
flows use --print-auth-url then --callback-url or --auth-code; --json
makes the output machine-readable.
"Other providers are disabled in this build"#
That is expected on a public release. See Providers. The error text is literal:
Other providers are disabled in this build (ENABLE_OTHER_PROVIDER=false).Model and credit problems#
A model is missing from /model#
The catalog is live and scoped to your credential and plan. Run
/refresh-model-list, then /model again. If it is still absent, your plan does
not include it. See Models.
"Insufficient credits" or a hard stop mid-turn#
rayu usage # current period, remaining and usedCheck the reset date in rayu account status, or top up from the dashboard. See
Credits & limits.
A turn stalls with no output#
[provider] stream_idle_timeout_secs (default 180) aborts a request that
receives no data. Raise it for models that think for a long time:
[provider]
stream_idle_timeout_secs = 600Esc cancels a stuck turn without losing the partial answer. /fix runs the
recovery path when a session is in a bad state.
Terminal rendering problems#
Shift+Enter sends instead of adding a newline#
Run /terminal-setup once. Until then, a trailing \ followed by Enter
inserts a newline in every terminal.
Colors, emoji or block characters look wrong#
/theme previews themes, and /colors lets you set and score individual
colors. If your terminal lacks truecolor, pick a 256-color theme.
Mouse wheel scrolls the terminal instead of the transcript#
Mouse capture is on by default and blocks native selection. Alt+Y toggles
selection/copy mode; [display] mouse_capture = false turns it off permanently
at the cost of wheel scrolling.
Wide characters, emoji, and tmux are the usual causes of misaligned rows. Inside
tmux, set default-terminal "tmux-256color" and enable RGB.
MCP problems#
rayu mcp list # configured servers and auth state
rayu mcp test <server> # connect once and list tools
rayu mcp login <server> # OAuth for a remote serverIf a server is not listed, it is not in ~/.rayu/mcp.json, ./.mcp.json or
./.rayu/mcp.json, or it is disabled with "enabled": false. If its tools are
missing in a session but the server is healthy, /refresh-model-list is not
enough: restart the session; tool schemas are captured at session start. See
MCP servers.
Hooks do not run#
Check [hooks] in ~/.rayu/config.toml, then confirm the command is executable
and prints nothing unexpected. A pre_tool hook that exits 2 blocks the tool
on purpose; any other non-zero exit fails open. See Hooks.
Sessions#
Resuming the wrong session, or "no session found"#
rayu --resume # picker
rayu --resume <id> # specific sessionSessions are stored per project under ~/.rayu/sessions, keyed by the working
directory. Resuming from a different directory will not find the session; use
the picker, which searches across projects, or rayu session rename to give a
session a memorable name. See
Sessions & checkpoints.
The server will not reload#
rayu server reload # graceful, preserves sessions
rayu server reload --force # reload even if already current
rayu server stop --force # only for a wedged daemonstop drops in-flight sessions, which is why it requires --force.
Getting more information#
rayu --trace run "..." # tool I/O and token usage on stderr
rayu auth doctor # auth diagnosis
rayu provider-doctor rayu --tier full # strict end-to-end checkpoints
rayu support # email support, diagnostics prefilled/support (in a session) collects version, model, auth state and recent errors
so a bug report does not need a back-and-forth. /feedback sends a bug report or
idea without leaving the terminal.
Next: Documentation home →