Extension Not Connecting to Server

  1. Check server is running: Look for Gasoline server listening on http://localhost:7890
  2. Check extension badge: Red ! means disconnected, green means connected
  3. Check port conflict: Another process may be using port 7890. Try --port 7891
  4. Update extension URL: If using a different port, go to Options and change the Server URL
  5. Check browser console: Right-click extension icon → Inspect → Console tab

Logs Not Appearing

  1. Check capture level: Popup may be set to “Errors Only” — try “All Logs”
  2. Check domain filter: Options page may have filters excluding your domain
  3. Check log file: cat ~/gasoline-logs.jsonl | tail -5 to see recent entries
  4. Reload the page: Extension injects on page load

MCP Mode Not Working

  1. Check config path: Must be in your AI tool’s config directory
  2. Restart your AI tool: MCP servers are loaded on startup
  3. Check for JSON errors: Invalid JSON in config will silently fail
  4. Verify with AI: Ask “What MCP tools do you have?” — Gasoline tools should appear

Changing the Server Port

If port 7890 is in use:

npx gasoline-mcp --port 7891

Then update the extension:

  1. Click the Gasoline extension icon
  2. Click “Options”
  3. Change Server URL to http://localhost:7891
  4. Click “Save Options”

Using Debug Mode

The extension has built-in debug logging for troubleshooting:

  1. Enable: Open popup → scroll to “Debugging” → toggle “Debug Mode” on
  2. View logs: With debug mode on, activity appears in the browser console
  3. Export: Click “Export Debug Log” to download a JSON file

Debug Log Categories

Category What it captures
connection Server connection/disconnection events
capture Log capture, filtering, processing
error Extension internal errors
lifecycle Extension startup/shutdown
settings Configuration changes

The debug buffer holds 200 entries (circular — oldest are dropped). Logs are stored even when debug mode is off, so you can export after an issue occurs.

Reporting Issues

Open an issue with:

  1. Environment: OS, Chrome version, Gasoline version (window.__gasoline.version)
  2. Steps to reproduce
  3. Expected vs actual behavior
  4. Extension popup screenshot
  5. Debug log export (JSON file from popup)
  6. Browser console errors (right-click extension → Inspect → Console)
  7. Server output (any errors from npx gasoline-mcp)