## Troubleshooting

---

### Common Errors

---

#### Profile not configured

```
Error: No profile configured. Run 'rbw config create-profile' first.
```

**Solution**: Create a profile with:

```bash
rbw config create-profile
```

#### Authentication error (401)

```
Error: 401 Unauthorized
```

**Possible causes**:
- Expired or incorrect credentials
- Revoked API key
- Expired OAuth token

**Solutions**:
- Check your credentials: `rbw config show-profile`
- Update the profile: `rbw config update-profile <name>`
- For OAUTH, re-run the login flow

#### Module not found (ERR_MODULE_NOT_FOUND)

```
Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'xyz'
```

**Solution**: Reinstall the package:

```bash
npm install -g rainbow-cli-ng
```

#### Keyring not accessible

On some Linux systems without a graphical session (CI servers, Docker containers), the system keyring may not be available.

**Solution**: Configure a headless keyring or use `gnome-keyring` with D-Bus:

```bash
eval $(gnome-keyring-daemon --start)
export GNOME_KEYRING_CONTROL
```

#### Permission denied on rbw command

```
permission denied: rbw
```

**Solution**: Verify that the npm global bin directory is in your `PATH`:

```bash
npm config get prefix
# Add <prefix>/bin to your PATH if needed
```

### Debugging

---

#### Enable detailed logs

```bash
rbw --debug <command>
rbw --verbose <command>
```

The `--debug` option displays HTTP requests, authentication headers (masked) and full responses.

#### Write logs to a file

```bash
rbw --log debug.log <command>
```

Useful for analyzing issues in production environments without cluttering the console.

#### Check the installed version

```bash
rbw --version
```

### Getting Help

---

- Built-in help: `rbw --help` or `rbw <command> --help`
- Online documentation: [developers.openrainbow.com](https://developers.openrainbow.com)
- Rainbow support: [support@openrainbow.com](mailto:support@openrainbow.com)
