mcp-chrome/docs/TROUBLESHOOTING.md

Troubleshooting Guide 🔧

Common issues and solutions for Chrome MCP Server.

📋 Table of Contents

• Installation Issues
• Chrome Extension Problems
• Native Server Issues
• MCP Protocol Problems
• AI/SIMD Issues
• Performance Problems
• Network Capture Issues

🚀 Installation Issues

Node.js Version Compatibility

Problem: Build fails with Node.js version errors

Error: Unsupported Node.js version

Solution:

# Check Node.js version
node --version

# Install Node.js 18+ if needed
# Using nvm (recommended)
nvm install 18
nvm use 18

# Or download from nodejs.org

pnpm Installation Issues

Problem: pnpm command not found

bash: pnpm: command not found

Solution:

# Install pnpm globally
npm install -g pnpm

# Or using corepack (Node.js 16.10+)
corepack enable
corepack prepare pnpm@latest --activate

Build Failures

Problem: Build fails during pnpm build

Error: Build failed with exit code 1

Solutions:

# Clean and rebuild
pnpm clean
pnpm install
pnpm build

# Check for specific package issues
pnpm build:shared
pnpm build:wasm
pnpm build:native
pnpm build:extension

🔌 Chrome Extension Problems

Extension Not Loading

Problem: Extension fails to load in Chrome

Symptoms:

• "Manifest file is missing or unreadable"
• "Invalid manifest"
• Extension appears grayed out

Solutions:

1. Check build output:

cd app/chrome-extension
pnpm build
# Verify dist/ directory exists and contains manifest.json

2. Verify manifest.json:

cat app/chrome-extension/dist/manifest.json
# Should contain valid JSON with version 3

3. Enable Developer Mode:
   • Go to chrome://extensions/
   • Toggle "Developer mode" ON
   • Click "Load unpacked"
   • Select app/chrome-extension/dist

Native Messaging Connection Failed

Problem: Extension can't connect to native server

Error: Native host has exited

Solutions:

1. Check native server installation:

# Verify global installation
npm list -g mcp-chrome-bridge

# Reinstall if needed
cd app/native-server
npm install -g .

2. Verify native messaging manifest:

# macOS
cat ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.chromemcp.nativehost.json

# Linux
cat ~/.config/google-chrome/NativeMessagingHosts/com.chromemcp.nativehost.json

# Windows
# Check Registry: HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.chromemcp.nativehost

3. Check permissions:

# Ensure executable permissions
chmod +x /path/to/mcp-chrome-bridge

Extension Permissions Denied

Problem: Extension lacks necessary permissions

Solutions:

1. Grant permissions manually:

   • Right-click extension icon
   • Select "Options" or "Manage extension"
   • Enable all required permissions

2. Check manifest permissions:

{
  "permissions": [
    "nativeMessaging",
    "tabs",
    "activeTab",
    "scripting",
    "notifications",
    "downloads",
    "webRequest",
    "debugger",
    "history",
    "bookmarks",
    "offscreen",
    "storage"
  ],
  "host_permissions": ["<all_urls>"]
}

🖥️ Native Server Issues

Server Won't Start

Problem: Native server fails to start

Error: listen EADDRINUSE :::12306

Solutions:

1. Check port availability:

# Check if port 12306 is in use
lsof -i :12306
netstat -an | grep 12306

# Kill process using the port
kill -9 <PID>

2. Use different port:

# Set custom port
export NATIVE_SERVER_PORT=12307
mcp-chrome-bridge

Native Messaging Host Not Found

Problem: Chrome can't find native messaging host

Error: Specified native messaging host not found

Solutions:

1. Reinstall native host:

cd app/native-server
npm uninstall -g mcp-chrome-bridge
npm install -g .

2. Manual manifest installation:

# Create manifest directory
mkdir -p ~/.config/google-chrome/NativeMessagingHosts/

# Copy manifest
cp native-messaging-manifest.json ~/.config/google-chrome/NativeMessagingHosts/com.chromemcp.nativehost.json

🔗 MCP Protocol Problems

MCP Client Connection Issues

Problem: Claude Desktop can't connect to MCP server

Error: Failed to connect to MCP server

Solutions:

1. Check MCP configuration:

{
  "mcpServers": {
    "chrome-mcp-server": {
      "command": "mcp-chrome-bridge",
      "args": []
    }
  }
}

2. Verify server is running:

# Check if server is listening
curl http://localhost:12306/health

3. Check logs:

# Native server logs
tail -f ~/.local/share/mcp-chrome-bridge/logs/server.log

# Chrome extension logs
# Open Chrome DevTools -> Extensions -> Background Script

Tool Execution Timeouts

Problem: Tools timeout during execution

Error: Tool execution timeout after 30000ms

Solutions:

1. Increase timeout:

// In native server configuration
const response = await nativeMessagingHostInstance.sendRequestToExtensionAndWait(
  request,
  NativeMessageType.CALL_TOOL,
  60000, // Increase to 60 seconds
);

2. Check Chrome extension responsiveness:
   • Open Chrome DevTools
   • Check for JavaScript errors
   • Monitor memory usage

🧠 AI/SIMD Issues

SIMD Not Available

Problem: SIMD acceleration not working

Warning: SIMD not supported, using JavaScript fallback

Solutions:

1. Check browser support:

   • Chrome 91+ (May 2021)
   • Firefox 89+ (June 2021)
   • Safari 16.4+ (March 2023)
   • Edge 91+ (May 2021)

2. Enable SIMD flags (if needed):

# Chrome flags
chrome://flags/#enable-webassembly-simd

3. Verify WASM build:

cd packages/wasm-simd
pnpm build
# Check for simd_math.js and simd_math_bg.wasm in pkg/

AI Model Loading Failures

Problem: Semantic similarity engine fails to initialize

Error: Failed to load AI model

Solutions:

1. Check model files:

# Verify model files exist
ls app/chrome-extension/public/models/
# Should contain model.onnx, tokenizer.json, etc.

2. Clear browser cache:

   • Open Chrome DevTools
   • Application tab -> Storage -> Clear storage

3. Check memory usage:

   • Monitor Chrome task manager
   • Ensure sufficient RAM available (>2GB recommended)

Vector Database Issues

Problem: Vector search not working

Error: Vector database initialization failed

Solutions:

1. Clear IndexedDB:

   • Chrome DevTools -> Application -> IndexedDB
   • Delete "VectorDatabase" entries

2. Check WASM loading:

// In browser console
console.log(typeof WebAssembly);
// Should return "object"

⚡ Performance Problems

High Memory Usage

Problem: Extension uses excessive memory (>500MB)

Solutions:

1. Reduce cache sizes:

// In semantic-similarity-engine.ts
const config = {
  cacheSize: 100, // Reduce from default 500
  maxElements: 5000, // Reduce vector DB size
};

2. Clear caches periodically:

// Clear embedding cache
semanticEngine.clearCache();

// Clear vector database
vectorDatabase.clear();

Slow Tool Execution

Problem: Tools take >5 seconds to execute

Solutions:

1. Check content script injection:

// Verify scripts are cached
chrome.scripting.getRegisteredContentScripts();

2. Optimize selectors:

// Use efficient selectors
'#specific-id'; // Good
'.class-name'; // OK
'div > span.class'; // Better than complex selectors

3. Monitor performance:

// Add timing logs
console.time('tool-execution');
// ... tool code ...
console.timeEnd('tool-execution');

🌐 Network Capture Issues

No Requests Captured

Problem: Network capture returns empty results

Solutions:

1. Check permissions:

   • Ensure "webRequest" permission is granted
   • Verify host permissions include target domain

2. Verify capture timing:

// Start capture before navigation
await callTool('chrome_network_capture_start');
await callTool('chrome_navigate', { url: 'https://example.com' });
// Wait for page load
await new Promise((resolve) => setTimeout(resolve, 3000));
await callTool('chrome_network_capture_stop');

3. Check filters:
   • Disable static resource filtering if needed
   • Verify URL patterns match

Debugger API Issues

Problem: Debugger capture fails

Error: Cannot attach debugger to this target

Solutions:

1. Check tab state:

   • Ensure tab is not a Chrome internal page
   • Verify tab is fully loaded

2. Detach existing debuggers:

// In Chrome DevTools console
chrome.debugger.getTargets().then((targets) => {
  targets.forEach((target) => {
    if (target.attached) {
      chrome.debugger.detach({ targetId: target.id });
    }
  });
});

🆘 Getting Help

If you're still experiencing issues:

1. Check GitHub Issues: github.com/hangwin/chrome-mcp-server/issues

2. Create a Bug Report with:

   • Operating system and version
   • Chrome version
   • Node.js version
   • Complete error messages
   • Steps to reproduce

3. Enable Debug Logging:

# Set debug environment
export DEBUG=chrome-mcp-server:*
mcp-chrome-bridge

4. Collect Logs:

   • Chrome extension console logs
   • Native server logs
   • MCP client logs

5. Test with Minimal Setup:

   • Fresh Chrome profile
   • Clean installation
   • Default configuration

Remember to include relevant logs and system information when reporting issues!