Debugging Chrome Extensions Like a Pro

Extension debugging is different from web debugging. You are not working with one context — you are juggling multiple isolated JavaScript environments that communicate through message passing. The popup has its own DevTools. The background service worker has its own DevTools. Each content script runs in its own isolated world on each page. And errors in one context can silently affect behavior in another.

Most extension bugs are not hard to fix. They are hard to find. This guide gives you a systematic approach to locating bugs across every execution context, using the tools Chrome provides.

Debugging by context#

Each part of a Chrome extension runs in a different environment with different capabilities and different debugging access points. Pick the tab that matches where your bug lives.

Systematic debugging process#

When something is not working and you do not know why, resist the urge to add random console.log statements. Follow a structured process.

Common error messages and fixes#

These are the extension errors developers encounter most frequently, along with the actual causes and solutions.

Essential debugging techniques#

Console filtering#

When debugging content scripts, the page's console is shared between your code and the page's own JavaScript. Use console filtering to see only your output.

// Prefix all your console output with a tag
const log = (...args: unknown[]) => console.log('[MyExtension]', ...args);
const warn = (...args: unknown[]) => console.warn('[MyExtension]', ...args);
const error = (...args: unknown[]) => console.error('[MyExtension]', ...args);
 
// Usage
log('Content script initialized on', window.location.href);
warn('Element not found, retrying in 500ms');

In DevTools Console, type [MyExtension] in the filter box. Now you see only your extension's output, even on pages with hundreds of their own console messages.

Network monitoring for extensions#

Service worker network requests do not appear in the page's Network tab. You need to inspect the service worker's own DevTools.

// Add request/response logging to your service worker
const originalFetch = globalThis.fetch;
globalThis.fetch = async (input: RequestInfo | URL, init?: RequestInit) => {
  const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
  console.log(`[Fetch] ${init?.method || 'GET'} ${url}`);
  const startTime = performance.now();
 
  try {
    const response = await originalFetch(input, init);
    const duration = Math.round(performance.now() - startTime);
    console.log(`[Fetch] ${response.status} ${url} (${duration}ms)`);
    return response;
  } catch (err) {
    console.error(`[Fetch] FAILED ${url}`, err);
    throw err;
  }
};

Storage inspector#

The Application tab in DevTools has an "Extension Storage" section (under Storage) that lets you view and edit chrome.storage.local and chrome.storage.sync values in real time. This is faster than writing console commands.

For programmatic inspection during debugging, add a helper to your service worker:

// Dump all storage contents to console
async function debugStorage() {
  const local = await chrome.storage.local.get(null);
  const sync = await chrome.storage.sync.get(null);
  const session = await chrome.storage.session.get(null);
 
  console.group('Extension Storage Debug');
  console.log('Local:', JSON.stringify(local, null, 2));
  console.log('Sync:', JSON.stringify(sync, null, 2));
  console.log('Session:', JSON.stringify(session, null, 2));
  console.log('Sync bytes used:', await chrome.storage.sync.getBytesInUse(null), '/ 102400');
  console.groupEnd();
}
 
// Call from console: debugStorage()
// Or attach to a debug keyboard shortcut

Message passing debugging#

Message passing bugs are the most common source of "it works sometimes" behavior. Add tracing to both sides:

// In your service worker — log all incoming messages
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  console.log('[MSG IN]', {
    type: message.type,
    data: message,
    from: sender.tab ? `Tab ${sender.tab.id}: ${sender.tab.url}` : 'Extension',
    frameId: sender.frameId,
  });
 
  // Your actual handler logic here
  // IMPORTANT: return true if sendResponse will be called asynchronously
  return true;
});
 
// In your content script — log outgoing messages and responses
async function sendMessage<T>(message: { type: string; [key: string]: unknown }): Promise<T> {
  console.log('[MSG OUT]', message);
  try {
    const response = await chrome.runtime.sendMessage(message);
    console.log('[MSG RESP]', response);
    return response as T;
  } catch (err) {
    console.error('[MSG ERR]', err);
    throw err;
  }
}

Breakpoints in content scripts#

To set breakpoints in content scripts:

1. Open DevTools on the page (F12)
2. Go to Sources panel
3. In the left sidebar, expand "Content scripts"
4. Find your extension's ID folder
5. Open the content script file
6. Click the line number to set a breakpoint

For conditional breakpoints that only trigger on specific pages or elements:

// Instead of plain breakpoints, use programmatic debugger statements
// with conditions — easier to manage than DevTools conditional breakpoints
 
function processElement(el: HTMLElement) {
  // This breakpoint only triggers for elements with the target class
  if (el.classList.contains('debug-target')) {
    debugger; // DevTools will pause here if open
  }
  // ... rest of your logic
}

Chrome extension debugging flags#

Chrome has hidden flags that make extension development easier. Navigate to chrome://flags and enable these:

• Extensions Developer Mode: Already available on chrome://extensions — enables loading unpacked extensions, shows errors, and provides the "Update" button for reloading.
• Enable extension service worker keepalive: Under chrome://flags/#enable-extension-service-worker-keepalive — extends the 30-second timeout during debugging. Useful for testing but do not rely on it for production behavior.

On the chrome://extensions page itself:

• Developer mode toggle (top right): Must be on for unpacked extensions and shows the "Errors" button per extension.
• Update button: Forces all extensions to reload their service workers and re-inject content scripts. Faster than removing and re-adding the extension.

Debugging performance issues#

Slow extensions frustrate users and can trigger Chrome's performance warnings. Use these techniques to find bottlenecks.

Content script performance: If your content script makes pages slow, open DevTools Performance tab and record a page load. Your content script's execution time appears in the "Main" thread flame chart. Filter for your extension ID. If it takes more than 50ms, optimize by deferring non-critical work with requestIdleCallback().

Service worker startup time: Service workers that take too long to start cause delayed responses to user actions. Measure startup time by adding performance.mark('sw-start') at the top of your service worker and performance.mark('sw-ready') after all listeners are registered. Use performance.measure('sw-init', 'sw-start', 'sw-ready') to see the duration.

Storage read performance: chrome.storage.local.get() can be slow if you are storing large objects. Instead of one key with a huge JSON blob, split data into multiple keys and read only what you need. Reading a specific key is O(1); reading null (all keys) is O(n).

// Slow: reads everything, even if you only need one setting
const all = await chrome.storage.local.get(null);
const theme = all.settings?.theme;
 
// Fast: reads only the specific key
const { theme } = await chrome.storage.local.get('theme');

For a deeper understanding of service worker architecture that affects debugging, read our guide on background service workers deep dive. And for permission-related debugging, see Manifest V3 permissions best practices.