# Troubleshooting

Start with `/doctor` — it checks runtime version, provider credentials, config integrity, plugin/MCP status, and Sentry telemetry.

## Startup Issues

### "command not found: clew"

npm global install path may not be in `PATH`. Use `npx clew-code` or `bun x clew-code` as alternatives.

### "Bun not found"

Clew requires Bun 1.3+ as the runtime for the npm package.

## Provider Issues

### "No API key configured"

Set at least one provider API key as an environment variable. See Providers for the full list.

    export ANTHROPIC_API_KEY=sk-ant-...
    export DEEPSEEK_API_KEY=sk-...

Run `/doctor` to verify configured providers.

### "Rate limited" or "Quota exceeded"

Set a fallback model via CLI: `--fallback-model <model>`. Or use `/model` to switch to a different provider. For rate limit options during a session, use `/rate-limit-options`.

## Build Issues

### TypeScript errors during build

    bun run build
    # TypeScript errors may exist in uncommitted code or external modules.
    # Run targeted checks:
    bun x tsc --noEmit
    bun test

### Windows-specific issues

- ripgrep is bundled at `src/utils/vendor/ripgrep/x64-win32/rg.exe`
- TTY polyfill may be needed for Ink compatibility
- PowerShell and Bash may behave differently for tool execution
- Windows argv normalization in `src/entry.ts`

## MCP Issues

### "MCP server connection failed"

Verify the server command exists and paths are correct. Check JSON config syntax with `/mcp` command.

### MCP tools not appearing

Use `/mcp` to check server status. Tools are loaded at startup via `--mcp-config` or through `assembleToolPool()` during server connection. Verify the server implements `tools/list` correctly.

## Plugin Issues

### Plugin not loading

Check plugin manifest format and location. Use `/plugin` and `/reload-plugins` to refresh. For directory-based plugins, use `--plugin-dir <path>`.

## Feature Flags

Some features require compile-time or runtime flags:

Feature | Required Flag
--- | ---
Bridge mode | `BRIDGE_MODE=1`
Voice mode | `VOICE_MODE=1`
LSP tool | `ENABLE_LSP_TOOL=1`
Computer Use | `ENABLE_COMPUTER_USE=1` (Windows)
Proactive features | `KAIROS=1`
Agent triggers | `AGENT_TRIGGERS=1`
Code index | `CODE_INDEX=1`

## Getting Help

- In-app diagnostics: `/doctor` — comprehensive environment check
- Status overview: `/status` — version, model, API connectivity, tool statuses
- GitHub Issues: Report bugs and feature requests
- Debug mode: Run with `DEBUG=1` or `DEBUG=provider:anthropic` for detailed logging