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

# Troubleshooting

> This section covers common issues when installing or starting OpenBug CLI, based on expected behavior in the codebase.

#### Prerequisites checklist

* Node.js 20+ installed on your system.
* `@openbug/cli` installed globally (`npm install -g @openbug/cli`).
* Valid API key from OpenBug Web Studio.
* `openbug.yaml` present in the project root (automatically created after running first script using `debug` as a prefix).

***

## 🛑 **ERROR: debug: command not found**

* **Cause**: Global npm bin directory not on your `PATH`, or install didn't succeed.
* **Fix**:
  * Confirm install: `npm list -g --depth=0 | grep @openbug/cli`
  * Check global bin: `npm bin -g` and ensure that directory is on your shell `PATH`.
  * Reinstall if needed: `npm install -g @openbug/cli`

***

## 🛑 **ERROR: API key / authentication issues**

**Note**: Ensure your API key is active in the OpenBug Web Studio.

**Symptoms may include:**

* CLI printing an error that `API_KEY` is missing or empty.
* WebSocket connection closing immediately after start.

**Checks:**

1. Open `~/.openbug/config` and ensure it contains:

   ```bash theme={null}
   API_KEY=your-api-key-here
   ```
2. If the file doesn't exist or `API_KEY` is empty:

   ```bash theme={null}
   debug login <your-api-key>
   ```
3. Re-run your command under OnCall (e.g., `debug npm run dev`).

***

## 🛑 **ERROR: Missing openbug.yaml in project**

**Symptoms:**

* CLI can't infer project identity (`id`, `window_id`).
* Cluster lookups return nothing for this directory.

**Fix:**

```bash theme={null}
cd /path/to/your/project
debug init -m "Describe this service" -id "openbug-service"
```

This creates `openbug.yaml` with sensible defaults. Use the same `id` as mentioned above across related services.

***

## 🛑 **ERROR: Cluster server not reachable**

**Symptoms:**

* CLI unable to register/fetch project metadata from `OPENBUG_CLUSTER_URL`.
* Architecture sent to backend only includes the current service.

**Checks:**

1. Ensure `oncall cluster` is running in another terminal on the same machine.
2. Default URL is `ws://127.0.0.1:4466`. If you override `ONCALL_CLUSTER_URL`, confirm host/port.
3. If cluster isn't needed, you can ignore this and still debug that one service.

***

## 🛑 **ERROR: Access denied for tools**

**Symptoms:**

* AI responses indicating it cannot access logs or code for this service.
* Tool calls returning messages like "No Access to execute X".

**Checks:**

1. Open the service's `openbug.yaml` and verify:

   ```yaml theme={null}
   logs_available: true
   code_available: true
   ```
2. For **production** environments, it's expected that `code_available` may be `false`. In that case:
   * AI can still work with logs (if `logs_available: true`).
   * Code tools will not be used for that service.

***

## 🛑 **ERROR: Logs not appearing in the UI**

**Symptoms:**

* Command runs but Logs pane stays empty or incomplete.

**Checks:**

1. Confirm the command actually produces stdout/stderr when run **without** openbug.
2. Verify you're running the command prefixed with `debug`, not inside an already-running OpenBug shell.

***

> If these checks don't resolve your issue, capture the command you ran, the error output, and redacted config files to share with your support channel.