> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rye.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fix common Rye installation, auth, proxy, CA, shim, and capture issues.

Start with the doctor command:

```bash theme={null}
rye doctor
```

Apply safe local fixes:

```bash theme={null}
rye doctor --fix
```

## `rye` command not found

Confirm the install directory is on `PATH`.

Default user installs use:

```txt theme={null}
$HOME/.local/bin
```

Add it for zsh or bash:

```bash theme={null}
export PATH="$HOME/.local/bin:$PATH"
```

Restart your shell and verify:

```bash theme={null}
rye version
```

## Not logged in

Check auth state:

```bash theme={null}
rye auth status
```

Sign in:

```bash theme={null}
rye auth login
```

If `rye up` starts login automatically, complete the browser flow and return to the terminal.

## Daemon is not running

Check daemon state:

```bash theme={null}
rye daemon status
```

Start or restart it:

```bash theme={null}
rye daemon start
rye daemon restart
```

Read logs:

```bash theme={null}
rye daemon logs --lines 100
```

## No traffic is captured

Check these first:

* Start the agent after setting proxy variables or use `rye wrap`.
* Confirm `rye status` shows the proxy is running.
* Confirm the target domain matches your intercept patterns.
* Check whether `NO_PROXY` excludes the target host.
* For GUI apps, use `--auto-configure-proxy` or launch the app from a shell that has proxy variables.
* Use `--intercept-all` temporarily to separate pattern issues from routing issues.

Example:

```bash theme={null}
rye up --intercept-all --install-ca
rye wrap claude
```

## TLS or certificate errors

Verify the CA exists:

```bash theme={null}
rye ca path
```

Install the CA:

```bash theme={null}
rye ca install
```

For Node-based tools, confirm `NODE_EXTRA_CA_CERTS` points to the Rye CA. `rye wrap` injects this when the CA exists.

For tools with product-specific trust variables, set the documented CA variable manually:

```bash theme={null}
export CODEX_CA_CERTIFICATE="$(rye ca path)"
export SSL_CERT_FILE="$(rye ca path)"
```

Avoid disabling certificate verification except in a disposable test shell.

## App shims are not taking effect

Run:

```bash theme={null}
rye app doctor
```

The shims directory must appear before the real app directories on `PATH`.

For zsh or bash:

```bash theme={null}
export PATH="$HOME/.rye/shims:$PATH"
```

Restart your shell, then check:

```bash theme={null}
which claude
which codex
rye app list
```

## System proxy did not restore

Stop Rye:

```bash theme={null}
rye down
```

If the daemon is not reachable, restart it and stop again:

```bash theme={null}
rye daemon restart
rye down
```

Then inspect your OS proxy settings. Rye can only restore settings it configured during the current proxy lifecycle.

## Policy blocked a request

Blocked requests return `403` with a JSON body that includes:

* `request_id`
* `decision`
* `rule_id`
* `rule_version`
* `reason`

Inspect recent history:

```bash theme={null}
rye history --last 10m
rye history export --format json --last 10m
```

Use the `request_id` to correlate the block with local logs and control-plane events.

## History is empty

Check whether:

* The proxy is running.
* The request domain matches intercept patterns.
* The app is using the proxy.
* The request is model API traffic, not package manager, Git, browser, or unrelated network traffic.
* You are querying the right time window.

Try:

```bash theme={null}
rye history --last 24h
```

## Need support

Email [security@rye.ai](mailto:security@rye.ai) with:

* `rye version`
* `rye status --json`
* `rye doctor --json`
* The command you ran.
* The exact error message.