How to Debug Your Chrome Extension: The Complete Guide

Your Chrome extension installs fine. The icon appears in the toolbar. But when you click it, nothing happens. No error in the console. No crash. Just silence. You open DevTools on the page and see nothing because the extension runs in a completely different context. This is the moment most developers realize that debugging a Chrome extension is not like debugging a web app.

The core challenge is that a Chrome extension is not one program. It is several programs running in isolated environments that communicate through message passing. Your popup, background service worker, and content scripts each have their own console, their own errors, and their own DevTools window. If you are looking in the wrong place, you will never find the bug. Once you understand where each piece of your extension runs and how to inspect it, debugging becomes straightforward. If you are still setting up your first extension, start with how to create a Chrome extension from the ground up before diving into debugging.

Why Chrome Extension Debugging Is Different

A normal web app runs in one page with one DevTools window. A Chrome extension splits its logic across at least two or three separate execution contexts. The popup is its own small HTML page that opens and closes every time the user clicks the icon. The background service worker runs without any visible page at all. Content scripts run inside the web page the user is viewing, but in an isolated JavaScript environment that cannot directly access the page's variables.

Each of these contexts has its own console. A console.log in your service worker will never appear in the popup's DevTools. An error in your content script will not show up on the chrome://extensions page. This is why so many developers think their code is not running when it actually is. They are just looking in the wrong console.

An extension is not one program. It is several programs in isolated worlds that talk by passing messages — and each world has its own console you have to open on purpose.

Debugging the Popup

Right-click your extension icon in the toolbar and select "Inspect popup." This opens a DevTools window attached specifically to your popup's HTML page. You will see your console logs, network requests, and any errors that occur while the popup is open.

1. 1

   Inspect the popup

   Right-click the toolbar icon and choose "Inspect popup." DevTools attaches to the popup's own HTML page, with its console, network tab, and errors.

2. 2

   Inspect the service worker

   Open chrome://extensions, find your extension, and click the "service worker" link. This is the only place the background script's logs and errors appear.

3. 3

   Inspect content scripts

   Open the host page's own DevTools, go to the Sources panel, and find your files under the "Content scripts" section. Breakpoints work like any other script.

The most common popup issue is that it closes the instant you click anywhere outside of it, which also closes the attached DevTools window and clears everything you were looking at. To work around this, add a debugger statement in your popup code. When DevTools hits the breakpoint, the popup stays open. Alternatively, you can log to the background service worker using chrome.runtime.sendMessage and inspect those logs in the service worker console instead.

If your popup opens as a blank white rectangle, the problem is almost always a wrong file path in your manifest's default_popup field or a build step that is not outputting your popup HTML to the expected directory. Check your manifest first, then check your build output folder.

Debugging the Background Service Worker

Open chrome://extensions in your browser, find your extension, and click the "service worker" link. This opens DevTools for your background script. Any console.log, error, or network request from the service worker appears here.

The biggest gotcha with Manifest V3 service workers is that they stop running when idle. If you open the service worker DevTools and see an empty console, it is probably because the worker terminated and restarted since your last log. Anything logged before the restart is gone. To catch errors that happen at startup, add your logging at the very top of your service worker file so it executes immediately when the worker spins up.

If you see "service worker registration failed" on the chrome://extensions page, the problem is usually a syntax error in your service worker file or a missing file reference. Click the error link for details, fix the syntax, and reload the extension. For extensions built with React and TypeScript, a misconfigured build that outputs ES modules instead of a plain script will also cause this error. See how to build a Chrome extension with React and TypeScript for the correct build setup.

Debugging Content Scripts

Content scripts run inside the web page, so you debug them using the page's own DevTools. Right-click the page, select "Inspect," and open the Sources panel. Look for your extension's content script files under the "Content scripts" section in the left sidebar. You can set breakpoints, step through code, and inspect variables just like any other JavaScript.

The most common content script bug is trying to access a DOM element that has not loaded yet. If your script runs at document_start, the page body may be empty. Switch to document_idle in your manifest or wrap your logic in a DOMContentLoaded listener. The second most common issue is message passing failures between the content script and the background service worker. If chrome.runtime.sendMessage silently fails, check that your service worker has a matching chrome.runtime.onMessage listener and that the extension has not been reloaded since the content script was injected.

Common Errors and How to Fix Them

A handful of error messages account for most of the time developers lose. Here is what each one is really telling you and the fix that clears it.

• Cannot access contents of url

  A permission error. Your manifest is missing a required host permission or the activeTab permission for the page you are trying to interact with. Add the specific host to your manifest's permissions array and reload.

• Content Security Policy violations

  These appear when your extension tries to load external scripts, use eval, or use inline event handlers. Manifest V3 enforces a strict CSP by default. Move inline scripts into separate files, avoid eval entirely, and fetch any external resource from your service worker, then pass the data to your popup or content script.

• Could not establish connection. Receiving end does not exist

  The listener for your message is not registered. This usually happens when a content script sends a message but the service worker has gone idle, or when the popup messages a content script on a tab where it was never injected. Confirm both sides of a message channel are active before sending.

• Service worker registration failed

  Usually a syntax error or a missing file reference in the service worker, or — for React and TypeScript builds — a config that outputs ES modules instead of a plain script. Click the error link on chrome://extensions for details, fix it, and reload.

Tools That Make Debugging Easier

The chrome://extensions page is your command center. Enable "Developer mode" in the top right corner to see the "Reload" button, error logs, and the service worker inspector link for each extension. After every code change, click "Reload" to pick up the new version instantly without uninstalling and reinstalling.

For extensions that modify web pages, use the Elements panel in the page's DevTools to verify that your content script is actually changing the DOM. If you are injecting UI elements, inspect them to make sure styles are not being overridden by the host page's CSS. Using a Shadow DOM for injected UI isolates your styles and prevents conflicts.

Add structured error logging early. A simple pattern is to wrap your key functions in try-catch blocks that log errors with context, such as which function failed and what arguments it received. When you have hundreds of users and cannot reproduce a bug locally, these logs are the only way to diagnose the issue. For tracking errors in production, consider integrating a lightweight error reporting service or the Google Analytics Measurement Protocol to send error events from your extension.

Frequently Asked Questions

The short answers below cover the bugs developers hit most when an extension installs cleanly but appears dead. The common thread: the code is usually running fine — you just need to open the right console and account for the Manifest V3 service worker's habit of going idle.

Why does nothing happen when I click my extension and the console is empty?

How do I keep my popup's DevTools open when it closes on click?

Why is my service worker console empty?

What causes 'Could not establish connection. Receiving end does not exist'?

Why does my popup open as a blank white rectangle?

Ship With Fewer Bugs From Day One

Most debugging pain comes from misconfigured manifests, incorrect file paths, and permission mismatches. These are setup problems, not logic problems. They burn hours because they produce silent failures instead of clear error messages. The fastest way to avoid them is to start with a foundation that is already configured correctly.

ExtensionFast gives you a production-ready Manifest V3 project with the service worker, popup, and content script wiring already set up and tested. Permissions are minimal by default, the build pipeline outputs files exactly where Chrome expects them, and the project structure keeps each execution context cleanly separated so you always know where to look when something goes wrong. Instead of debugging your build configuration, you can focus on debugging your actual feature logic. If you want to get your extension reviewed and approved quickly after debugging, read how to pass the Chrome Web Store review on your first try.

Ship a Chrome extension that makes money, built by your AI agent, with ExtensionFast.