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

# Troubleshooting

> Common issues and solutions for Calmo Bridge IDE

# Troubleshooting

This guide covers common issues with Calmo Bridge IDE and how to resolve them.

## Connection Issues

### Bridge Shows "DISCONNECTED"

<AccordionGroup>
  <Accordion title="Check Internet Connection">
    Ensure your machine has internet access and can reach `app.getcalmo.com`.

    Test with:

    ```bash theme={null}
    curl -I https://app.getcalmo.com
    ```
  </Accordion>

  <Accordion title="Verify Server URL">
    The Server URL should be `https://app.getcalmo.com/` (default). If you're using a custom deployment, verify the URL is correct.
  </Accordion>

  <Accordion title="Restart the Bridge">
    1. Quit the bridge completely (don't just close the window)
    2. Relaunch from Applications/Start Menu
    3. Try connecting again
  </Accordion>

  <Accordion title="Check Firewall/VPN">
    Some firewalls or VPNs may block WebSocket connections. Try:

    * Temporarily disabling the firewall
    * Disconnecting from VPN
    * Adding an exception for Calmo Bridge IDE
  </Accordion>
</AccordionGroup>

### Pairing Code Expired

Pairing codes expire after **10 minutes**. If your code expired:

1. Go to [app.getcalmo.com/integrations/bridge](https://app.getcalmo.com/integrations/bridge)
2. Click **Generate New Code**
3. Enter the new code in the bridge app

### Device Not Appearing in Web Interface

If your paired device doesn't show as connected:

1. Check the bridge app shows a green status with device code
2. Refresh the web page
3. Click the refresh icon next to "Connected Devices"
4. Try unpairing and re-pairing the device

### "Enter Code" State Persists

If the bridge is stuck showing "ENTER CODE" after pairing:

1. Close and reopen the bridge IDE window
2. Check the Logs tab for error messages
3. Try generating a new pairing code

## Command Execution Issues

### Command Hangs / No Response

<AccordionGroup>
  <Accordion title="Check Pending Commands">
    The command might be waiting for approval. Check the **Pending Commands** section in the Bridge tab.
  </Accordion>

  <Accordion title="Command Timeout">
    Some commands may time out if they take too long. For long-running operations:

    * Use commands with built-in output streaming
    * Consider breaking into smaller operations
  </Accordion>

  <Accordion title="Process Stuck">
    If a command process is stuck:

    * Check the Logs tab for errors
    * The bridge may need to be restarted
  </Accordion>
</AccordionGroup>

### "Command Not Found" Errors

```
Error: command not found: kubectl
```

**Solutions:**

1. **Verify installation**
   ```bash theme={null}
   which kubectl
   ```

2. **Check PATH**
   The bridge inherits your shell's PATH. Ensure the command is in your PATH:
   ```bash theme={null}
   echo $PATH
   ```

3. **Use full path**
   Ask Calmo to use the full path:
   ```bash theme={null}
   /usr/local/bin/kubectl get pods
   ```

### Permission Denied

```
Error: Permission denied
```

**Solutions:**

1. Check file/directory permissions
2. Commands run with your user permissions—not root
3. For operations requiring sudo, the bridge will need appropriate setup

### Command Denied But You Didn't Deny It

This can happen if:

* The web session timed out
* You denied it from another browser tab
* The bridge lost connection during approval

Check the command history and try again.

## MCP Server Issues

### Server Won't Start

<AccordionGroup>
  <Accordion title="Check command path">
    Verify the executable exists:

    ```bash theme={null}
    which npx
    # Should show: /usr/local/bin/npx
    ```

    Use the full path in your config:

    ```json theme={null}
    {
      "command": "/usr/local/bin/npx"
    }
    ```
  </Accordion>

  <Accordion title="Verify npm package">
    Ensure the package exists and can be installed:

    ```bash theme={null}
    npx -y @mastra/mcp-docs-server --help
    ```
  </Accordion>

  <Accordion title="Check logs">
    Look at the Logs tab for specific error messages:

    ```
    [MCP:server-name] stderr: Error: Cannot find module...
    ```
  </Accordion>
</AccordionGroup>

### Server Connected But Shows 0 Tools

1. **Wait for initialization** - Some servers take 10-30 seconds to load
2. **Check stderr** - Server may have logged initialization errors
3. **Reload servers** - Click **Reload Servers** in MCP Tools tab
4. **Verify package name** - Ensure you have the correct npm package

### HTTP Server Connection Failed

For HTTP MCP servers:

1. **Check URL format** - Include protocol (`https://`) and full path
2. **Verify API key** - Ensure key is valid and has correct permissions
3. **Test endpoint**
   ```bash theme={null}
   curl -H "Authorization: Bearer YOUR_KEY" https://server-url/mcp
   ```

### Windows: npx Not Working

On Windows, npx needs shell access. Wrap with `cmd /c`:

```json theme={null}
{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "@package/name"]
}
```

## UI Navigation Issues

### Can't Find Command History

If you can't locate past executed commands:

1. **Check the Activity tab** - Bottom panel has two tabs: Terminal and Activity
2. **Switch tabs** - Click "Activity" to see command history
3. **Expand commands** - Click the arrow next to any command to see full output
4. **Scroll** - History may extend beyond visible area

### Chat Interface Missing

If the chat panel isn't visible:

1. **Check right sidebar** - Chat should be in the right-most panel
2. **Expand sidebar** - Drag the divider if it's collapsed
3. **Restart bridge** - Close and reopen the application
4. **Check window size** - Ensure window is wide enough to show all panels

### Workspace Tree Collapsed

If you can't see your workspace files:

1. **Expand Workspaces section** - Click the arrow next to "Workspaces" in left sidebar
2. **Expand folders** - Click folder names to expand subfolders
3. **Check if workspaces added** - "3 workspaces" should show at bottom of sidebar
4. **Add workspace** - Click + button if no workspaces configured

### Terminal Panel Not Showing

If you don't see the terminal:

1. **Check bottom panel** - Terminal should be in the center-bottom area
2. **Click Terminal tab** - Ensure "Terminal" tab is selected (not "Activity")
3. **Resize** - Drag the divider between editor and terminal to expand
4. **Toggle** - Use Cmd/Ctrl+\` to show/hide terminal

### File Editor Won't Open

If the file editor doesn't appear:

1. **Click a file** - Select a file in the workspace tree
2. **Check center panel** - Editor should open in the center-top area
3. **Look for tabs** - File name should appear in a tab
4. **Close other tabs** - If too many tabs open, close some with ×

## Terminal Issues

### Terminal Output Not Showing

If commands execute but output doesn't appear:

1. **Check Terminal tab** - Ensure you're on "Terminal" (not "Activity")
2. **Scroll down** - Output might be below the visible area
3. **Wait for completion** - Some commands take time before showing output
4. **Check Activity tab** - Full output is always saved there

### Command Stuck in Terminal

If a command seems frozen:

1. **Check pending approval** - Look at Command Approval panel (top right)
2. **Approve the command** - Click Allow/Deny/Always
3. **Long-running process** - Some commands (like `npm install`) take time
4. **Interactive prompt** - Command might be waiting for input

### Terminal Colors/Formatting Broken

If terminal output lacks colors or formatting:

1. **Restart bridge** - Close and reopen to reset terminal
2. **Check command** - Some commands don't use colors
3. **Environment** - Ensure TERM environment variable is set

### Can't Scroll Terminal Output

If terminal output is cut off:

1. **Use scroll bar** - Right side of terminal panel
2. **Resize panel** - Drag divider to make terminal larger
3. **Check Activity tab** - Full output always available there
4. **Copy output** - Click copy icon to get full text

## File Editor Issues

### Can't Edit Files

If file editor is read-only or won't save changes:

1. **Check permissions** - Ensure file is writable
   ```bash theme={null}
   ls -la path/to/file
   ```
2. **Verify workspace** - File must be in a configured workspace
3. **Check file type** - Binary files show preview instead of editor
4. **Restart bridge** - Close and reopen the application

### File Changes Not Saving

If edits don't persist:

1. **Save manually** - Press Cmd/Ctrl+S
2. **Check disk space** - Ensure you have free space
   ```bash theme={null}
   df -h
   ```
3. **Verify write permissions** - File might be read-only
4. **Look for errors** - Check Activity Log for save errors

### File Changes Not Reflected

If saved changes aren't visible:

1. **Check auto-save** - Changes should save automatically
2. **Refresh file** - Close tab and reopen from workspace tree
3. **Check external edits** - Another program may have modified it
4. **Verify save** - Look for unsaved indicator (• dot in tab)

### Syntax Highlighting Not Working

If code appears without colors:

1. **Check file extension** - `.js`, `.py`, `.yaml` etc. trigger highlighting
2. **Reopen file** - Close tab and open again
3. **Language detection** - Some files may not be auto-detected
4. **Restart bridge** - Reload language parsers

### Too Many Tabs Open

If editor becomes cluttered:

1. **Close tabs** - Click × on each tab or Cmd/Ctrl+W
2. **Close all** - Right-click any tab → Close All
3. **Close others** - Right-click → Close Others
4. **Restart bridge** - Clears all tabs on reopen

## Workspace Issues

### Workspace Not Appearing

If workspace doesn't show in sidebar after adding:

1. **Check permissions** - Ensure directory is readable
   ```bash theme={null}
   ls -la /path/to/workspace
   ```
2. **Refresh** - Click refresh icon or restart bridge
3. **Verify path** - Confirm directory exists
4. **Check logs** - Activity Log may show errors

### Can't Add Workspace

If the Add Workspace dialog won't accept a directory:

1. **Check path** - Ensure directory exists
2. **Permissions** - You must have read access
3. **Already added** - Check "Current Workspaces" list for duplicates
4. **Path length** - Very long paths may cause issues

### Files Not Visible in Tree

If workspace is added but files don't appear:

1. **Expand folder** - Click arrow next to workspace name
2. **Permissions** - Ensure read access to subdirectories
3. **Hidden files** - Dot-files may not show
4. **Refresh** - Restart bridge to reload file tree

### Wrong Files Showing

If unexpected files appear in workspace:

1. **Check workspace path** - May have added parent directory
2. **Remove and re-add** - Delete workspace and add correct path
3. **Git ignore** - Some files may be filtered

## Installation Issues

### macOS: Terminal Features Not Working

If terminal functionality isn't working after installation on macOS:

<AccordionGroup>
  <Accordion title="Missing Build Tools">
    The IDE requires XCode Command Line Tools for terminal support:

    ```bash theme={null}
    xcode-select --install
    ```

    Follow the prompts to complete installation, then restart the bridge IDE.
  </Accordion>

  <Accordion title="Architecture Mismatch">
    On Apple Silicon (M1/M2/M3), ensure you're running the native ARM64 version:

    1. Quit the bridge
    2. Download the latest `.dmg` from the web interface
    3. Look for `arm64` or `universal` in the filename
    4. Reinstall and restart
  </Accordion>

  <Accordion title="Reinstall">
    Sometimes a clean reinstall fixes native module issues:

    1. Quit the bridge IDE completely
    2. Delete from Applications folder
    3. Clear application data:
       ```bash theme={null}
       rm -rf ~/Library/Application\ Support/Calmo\ Bridge\ IDE/
       ```
    4. Download and reinstall from the web interface
  </Accordion>
</AccordionGroup>

### Windows: Bridge Won't Start

If the bridge IDE fails to launch on Windows:

<AccordionGroup>
  <Accordion title="Missing Runtime">
    Windows requires Visual C++ Redistributable:

    1. Download from [Microsoft](https://aka.ms/vs/17/release/vc_redist.x64.exe)
    2. Install the package
    3. Restart your computer
    4. Launch the bridge again
  </Accordion>

  <Accordion title="Antivirus Blocking">
    Some antivirus software blocks native modules:

    1. Add an exception for `Calmo Bridge IDE.exe`
    2. Allow network connections for the application
    3. Restart the bridge IDE
  </Accordion>
</AccordionGroup>

### Linux: Terminal Commands Fail

On Linux, ensure you have basic build tools installed:

```bash theme={null}
# Debian/Ubuntu
sudo apt-get install build-essential

# Fedora/RHEL
sudo dnf install gcc-c++ make

# Arch
sudo pacman -S base-devel
```

Then restart the bridge IDE.

## Workspace Issues

### Workspace Not Accessible

If commands fail in a configured workspace:

1. **Verify path exists**
   ```bash theme={null}
   ls -la /path/to/workspace
   ```

2. **Check permissions** - Ensure you have read access to the directory

3. **Remove and re-add** - Delete the workspace and add it again

### Changes Not Reflected

If file changes aren't visible:

* Calmo doesn't cache workspace contents
* Changes should be immediately available
* Try running `ls` in the workspace to verify

## Performance Issues

### Bridge Using High CPU

1. **Check running processes** - A command might still be running
2. **Clear logs** - Large log history can impact performance
3. **Restart bridge IDE** - May clear accumulated state

### Slow Command Execution

1. **Check network latency** - Commands route through the server
2. **Simplify commands** - Break complex operations into steps
3. **Limit output** - Use flags like `--tail=100` to limit log output

### Memory Usage High

1. **Clear command history** - Click **Clear** in the Bridge tab
2. **Clear logs** - Click **Clear** in the Logs tab
3. **Restart bridge IDE** - Releases accumulated memory

## Browser Issues

### Safari/Brave Compatibility

Safari and Brave have limited WebSocket support. For best experience:

* Use **Chrome**, **Firefox**, or **Edge**
* Ensure browser is up to date

### Commands Not Appearing in Chat

If approved commands don't show results in the chat:

1. Check the browser console for errors
2. Refresh the Calmo web page
3. Verify the bridge still shows "Connected"

## Recovery Steps

### Full Reset

If nothing else works:

1. **Quit bridge IDE completely**
   * macOS: Right-click menu bar icon → Quit
   * Windows: Right-click tray icon → Exit

2. **Clear configuration** (optional)
   ```bash theme={null}
   # macOS
   rm -rf ~/Library/Application\ Support/Calmo\ Bridge\ IDE/

   # Windows
   rmdir /s %APPDATA%\Calmo\ Bridge\ IDE
   ```

3. **Reinstall bridge IDE**
   * Download fresh from the web interface
   * Reinstall the application

4. **Pair again**
   * Generate new pairing code
   * Complete pairing process

### Unpair and Re-pair

1. Go to [app.getcalmo.com/integrations/bridge](https://app.getcalmo.com/integrations/bridge)
2. Find your device under "Connected Devices"
3. Click the delete icon to remove it
4. Generate a new pairing code
5. Enter the code in your bridge app

## Getting Help

### Information to Provide

When contacting support, include:

* **Bridge IDE version** - Shown in the app title bar
* **Operating system** - macOS/Windows version
* **Error messages** - Copy from Logs tab
* **Steps to reproduce** - What you were doing when it failed

### Log Export

Copy relevant logs from the **Logs** tab to share with support.

### Contact Support

Email: **[support@getcalmo.com](mailto:support@getcalmo.com)**

Include:

* Description of the issue
* Screenshots if applicable
* Relevant log excerpts

***

*For additional help, contact our support team at [support@getcalmo.com](mailto:support@getcalmo.com).*