Troubleshooting

Common issues and how to fix them.

Server Issues

Port 9876 already in use

Error: listen EADDRINUSE: address already in use :::9876

Solution:

# Find what's using the port
lsof -i :9876

# Kill the process
kill -9 <PID>

# Or use a different port (not yet supported)

Server won't start

Check Node.js version:

node --version
# Requires Node.js 18+

Check for missing dependencies:

pnpm install
pnpm build

"Command not found: sidebutton"

If globally installed but not found:

# Check npm bin path
npm bin -g

# Add to PATH if needed
export PATH="$PATH:$(npm bin -g)"

Extension Issues

Extension not connecting

1. Is the server running?

   curl http://localhost:9876/health

2. Refresh the page and click "Connect This Tab" again

3. Check extension console:

   • Right-click extension icon
   • Click "Inspect popup"
   • Check Console for errors

"Connect This Tab" doesn't appear

• Make sure you're on a regular webpage (not chrome:// pages)
• Check that Developer mode is enabled in chrome://extensions/
• Try reloading the extension

Automation doesn't work on specific sites

Some sites block automation. Check:

1. Content Security Policy — Some sites block injected scripts
2. Login state — Some actions require authentication
3. Selector validity — Use capture_page to find correct selectors

Extension disconnects frequently

This can happen if:

• The server restarts
• Chrome suspends the service worker
• Network issues

Solution: Click the extension icon and reconnect.

Restricted Pages

Chrome enforces restrictions on certain URLs that prevent all extensions — including SideButton — from attaching the debugger, injecting content scripts, or performing any automation. These are Chrome-level restrictions, not SideButton limitations.

Fully Blocked

SideButton cannot operate on these pages at all:

URL Pattern	Description
chrome://*	Chrome internal pages (settings, extensions, flags, etc.)
chrome-extension://*	Other extensions' pages
devtools://*	Chrome DevTools
chrome-search://*	New Tab Page
chrome-untrusted://*	Sandboxed Chrome content
chrome-distiller://*	Reader mode pages
view-source:*	View source pages
chrome.google.com/webstore/*	Chrome Web Store (legacy)
chromewebstore.google.com/*	Chrome Web Store (current)
about:*	About pages (about:blank, about:newtab, etc.)
edge://*	Edge internal pages (Edge browser only)

Partially Restricted

These pages have limited functionality:

URL Pattern	Issue
file://*	Requires user opt-in: go to chrome://extensions/, find SideButton, and enable "Allow access to file URLs"
PDF viewer pages	Content scripts run but cannot interact with the PDF content itself
Sites with strict CSP	Some content script features may be blocked by the site's Content Security Policy

What Happens on Restricted Pages

• "Connect This Tab" will show an error: "Cannot connect to restricted URL"
• Embed buttons will not appear
• Workflows that target restricted pages will fail at the browser step

Solution: Navigate to a regular webpage (any http:// or https:// URL) before connecting.

Workflow Issues

"Workflow not found"

Error: Workflow not found: my_workflow

Check:

1. Workflow file exists in workflows/, actions/, or skills/ directory
2. File has .yaml extension
3. id in YAML matches the requested ID
4. If from a knowledge pack, verify it's installed: sidebutton install --list

"Browser not connected"

Error: BrowserNotConnected

Solution:

1. Install the Chrome extension
2. Navigate to a webpage
3. Click extension icon → "Connect This Tab"
4. Verify connection at localhost:9876

"Selector not found"

Error: Element not found: .my-selector

Check:

1. The selector is correct (use browser DevTools)
2. The element exists on the page
3. The page has fully loaded (add browser.wait step)

Find correct selector:

# Use the capture_page tool
curl -X POST http://localhost:9876/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"capture_page","arguments":{}}}'

"OpenAI API key not configured"

Error: OpenAI API key not configured

Solution:

Set the environment variable:

export OPENAI_API_KEY=sk-your-key-here
npx sidebutton

Or configure in Settings (dashboard).

LLM step returns error

Common causes:

• Invalid API key
• Rate limiting
• Model not available

Check:

# Test API key directly
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

MCP Issues

Claude/Cursor doesn't see SideButton

1. Check config file location:

   • Claude Code: ~/.claude/settings.json
   • Cursor: ~/.cursor/mcp.json
   • VS Code: .vscode/mcp.json

2. Verify JSON syntax — Use a JSON validator

3. Restart the AI tool after config changes

4. Check server is accessible:

   curl http://localhost:9876/health

"Server returned error"

MCP error -32603: ...

Common causes:

• Server not running
• Invalid parameters
• Browser not connected

Debug:

1. Check server logs (terminal where server is running)
2. Try the operation via dashboard first
3. Check run logs for details

Tools not appearing in AI tool

1. Restart the AI tool
2. Check config URL is exactly http://localhost:9876/mcp
3. Verify server responds to tools/list:

   curl -X POST http://localhost:9876/mcp \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Dashboard Issues

Dashboard shows "Server Disconnected"

1. Check server is running
2. Refresh the page
3. Check browser console for errors (F12)

Workflows don't appear

1. Check workflows/, actions/, and skills/ directories exist
2. Verify YAML files have correct structure
3. Check server logs for parsing errors

Run log is empty

Run logs are stored in run_logs/ directory. Check:

1. Directory exists and is writable
2. Workflows have been executed
3. Try running a workflow and check again

Getting Help

If you can't resolve your issue:

1. Check existing issues: GitHub Issues
2. Search discussions: GitHub Discussions
3. Open a new issue with:
   • Error message (full text)
   • Steps to reproduce
   • OS and Node.js version
   • Relevant logs

Debug Mode

For more detailed logs, set the DEBUG environment variable:

DEBUG=* npx sidebutton

This will show detailed information about:

• WebSocket connections
• Workflow execution
• MCP requests/responses