​

Troubleshooting

​

Connection Issues

​

Bridge Shows “DISCONNECTED”

curl -I https://app.getcalmo.com

​

Pairing Code Expired

1. Go to 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

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

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

​

Command Execution Issues

​

Command Hangs / No Response

​

”Command Not Found” Errors

Error: command not found: kubectl

1. Verify installation
   Copy

   which kubectl
   
2. Check PATH The bridge inherits your shell’s PATH. Ensure the command is in your PATH:
   Copy

   echo $PATH
   
3. Use full path Ask Calmo to use the full path:
   Copy

   /usr/local/bin/kubectl get pods
   

​

Permission Denied

Error: Permission denied

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

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

​

MCP Server Issues

​

Server Won’t Start

which npx
# Should show: /usr/local/bin/npx

{
  "command": "/usr/local/bin/npx"
}

npx -y @mastra/mcp-docs-server --help

[MCP:server-name] stderr: Error: Cannot find module...

​

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

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
   Copy

   curl -H "Authorization: Bearer YOUR_KEY" https://server-url/mcp
   

​

Windows: npx Not Working

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "@package/name"]
}

​

UI Navigation Issues

​

Can’t Find Command History

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

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

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

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

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

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

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

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

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

1. Check permissions - Ensure file is writable
   Copy

   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

1. Save manually - Press Cmd/Ctrl+S
2. Check disk space - Ensure you have free space
   Copy

   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

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

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

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

1. Check permissions - Ensure directory is readable
   Copy

   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

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

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

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

xcode-select --install

​

Windows: Bridge Won’t Start

​

Linux: Terminal Commands Fail

# Debian/Ubuntu
sudo apt-get install build-essential

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

# Arch
sudo pacman -S base-devel

​

Workspace Issues

​

Workspace Not Accessible

1. Verify path exists
   Copy

   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

• 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 - 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 - Releases accumulated memory

​

Browser Issues

​

Safari/Brave Compatibility

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

​

Commands Not Appearing in 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

1. Quit bridge completely
   • macOS: Right-click menu bar icon → Quit
   • Windows: Right-click tray icon → Exit
2. Clear configuration (optional)
   Copy

   # macOS
   rm -rf ~/Library/Application\ Support/Calmo\ Bridge/
   
   # Windows
   rmdir /s %APPDATA%\Calmo\ Bridge
   
3. Reinstall bridge
   • 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
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

• Bridge 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

​

Contact Support

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