Troubleshooting
Reference

Troubleshooting

10. Troubleshooting#

Start with these three, in this order. They answer most problems.

bash
rayu version                 # what is installed
rayu auth status             # is a credential configured
rayu account status          # plan, credits, reset date

Inside 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:

bash
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:

bash
which -a rayu        # macOS / Linux
where.exe rayu       # Windows

The 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:

bash
rayu update

checksum 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:

bash
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:

text
/logout
/login

v3 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#

bash
rayu login --provider rayu --no-browser

That 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:

text
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#

bash
rayu usage          # current period, remaining and used

Check 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:

toml
[provider]
stream_idle_timeout_secs = 600

Esc 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#

bash
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 server

If 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"#

bash
rayu --resume                 # picker
rayu --resume <id>            # specific session

Sessions 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#

bash
rayu server reload            # graceful, preserves sessions
rayu server reload --force    # reload even if already current
rayu server stop --force      # only for a wedged daemon

stop drops in-flight sessions, which is why it requires --force.

Getting more information#

bash
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 →