Skip to main content

​
Troubleshooting

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

​
Connection Issues

​
Bridge Shows “DISCONNECTED”

Ensure your machine has internet access and can reach app.getcalmo.com.Test with:
curl -I https://app.getcalmo.com
The Server URL should be https://app.getcalmo.com/ (default). If you’re using a custom deployment, verify the URL is correct.
  1. Quit the bridge completely (don’t just close the window)
  2. Relaunch from Applications/Start Menu
  3. Try connecting again
Some firewalls or VPNs may block WebSocket connections. Try:
  • Temporarily disabling the firewall
  • Disconnecting from VPN
  • Adding an exception for Calmo Bridge

​
Pairing Code Expired

Pairing codes expire after 10 minutes. If your 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

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 window
  2. Check the Logs tab for error messages
  3. Try generating a new pairing code

​
Command Execution Issues

​
Command Hangs / No Response

The command might be waiting for approval. Check the Pending Commands section in the Bridge tab.
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
If a command process is stuck:
  • Check the Logs tab for errors
  • The bridge may need to be restarted

​
”Command Not Found” Errors

Error: command not found: kubectl
Solutions:
  1. Verify installation 
    which kubectl
  2. Check PATH The bridge inherits your shell’s PATH. Ensure the command is in your PATH: 
    echo $PATH
  3. Use full path Ask Calmo to use the full path: 
    /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

Verify the executable exists:
which npx
# Should show: /usr/local/bin/npx
Use the full path in your config:
{
  "command": "/usr/local/bin/npx"
}
Ensure the package exists and can be installed:
npx -y @mastra/mcp-docs-server --help
Look at the Logs tab for specific error messages:
[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

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 
    curl -H "Authorization: Bearer YOUR_KEY" https://server-url/mcp

​
Windows: npx Not Working

On Windows, npx needs shell access. Wrap with cmd /c: 
{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "@package/name"]
}

​
Workspace Issues

​
Workspace Not Accessible

If commands fail in a configured workspace:
  1. Verify path exists 
    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 - 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

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 completely
    • macOS: Right-click menu bar icon → Quit
    • Windows: Right-click tray icon → Exit
  2. Clear configuration (optional) 
    # 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

When contacting support, include:
  • 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

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

​
Contact Support

Email: [email protected] Include:
  • Description of the issue
  • Screenshots if applicable
  • Relevant log excerpts
For additional help, contact our support team at [email protected].