Skip to main content

​
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: 
    API_KEY=your-api-key-here
  2. If the file doesn’t exist or API_KEY is empty: 
    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: 
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: 
    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.