Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 36 ยท Testing and Debugging

Debugging Every Extension Context

Find and fix extension bugs by opening the right DevTools for the service worker, popup, options page and content scripts, read the errors page, trace messages and fix the most common MV3 problems.

Debugging an extension feels odd at first because there is no single console. Your code runs in several separate places, and each has its own DevTools window. A console.log in the service worker will never appear in the page's console. Once you know where to look, debugging is straightforward. This lesson is a map of where each context lives and how to inspect it.

Load the extension unpacked

During development you load your folder directly, with no zip:

  1. Open chrome://extensions.
  2. Turn on Developer mode (top right).
  3. Click Load unpacked and choose the folder that contains manifest.json.

After editing code, click the reload (circular arrow) on your extension's card. For a content script, also refresh the web page: pages that were already open keep running the old script. Changes to the manifest always need a reload; changes to a popup's files appear the next time the popup opens.

One DevTools per context

Where each part is debugged

Service worker Card > Inspect views: service worker
Popup Right-click the popup > Inspect
Options page Right-click the page > Inspect
Content script Page DevTools > Sources > Content scripts

Four contexts, four consoles.

1 / 2
  • Service worker: on the extension card click the service worker link under "Inspect views". Its console, Sources panel and Network panel belong to the worker only. Closing that DevTools window keeps the worker alive while it is open, which can hide idle-shutdown bugs, so test with it closed too.
  • Popup: right-click the extension icon and choose Inspect popup, or right-click inside the open popup and choose Inspect. A popup closes when it loses focus, and its DevTools window closes with it unless you pop it out. For a popup that vanishes, open chrome-extension://<id>/popup.html in a normal tab: it works the same for layout and logic.
  • Options page: it is a normal page. Open it and use DevTools as usual.
  • Content script: open DevTools on the web page, go to Sources, then the Content scripts tree (or Page > your extension). In the Console, use the context drop-down (top left, normally "top") and pick your extension to run code in the content script's isolated world. Without that, window is the page's, not yours.

The Errors button

Uncaught exceptions and failed manifest parsing show up on the extension's card as Errors. Click it for the stack trace, the file and line, and the context. It also lists:

  • manifest errors ("Unrecognized manifest key", "Invalid value for permissions");
  • service worker registration failures (a syntax error in the worker means it never starts);
  • CSP violations in extension pages.

Fix the first error first: a worker that fails to register makes every later message fail.

Logging that helps

console.log is fine, but tag your messages by context so you can follow a flow in several consoles:

JavaScript
const TAG = "[sw]";
chrome.runtime.onMessage.addListener((msg, sender) => {
  console.log(TAG, "message", msg.type, "from", sender.tab ? "tab " + sender.tab.id : "extension page");
});

Use console.table, console.group and console.time to read bigger data. Pause with a debugger; statement or a breakpoint in Sources; a breakpoint inside a message handler pauses the whole flow so you can inspect the message.

A tagged logger for several contexts

A tagged logger with a level switch lets you ship verbose logs in development and quiet ones in production.

Common problems and where to look

Symptom Likely cause Check
"Service worker registration failed. Status code: 15" Syntax error or bad import in the worker Errors button, worker file
Content script does nothing Wrong matches, page not reloaded, runs too early Reload the page; check run_at
"Receiving end does not exist" No listener in the target tab Inject the script first, or catch the error
"Extension context invalidated" Extension reloaded while the page stayed open Refresh the page
Message port closed before a response Async reply without return true See One-time messages
Worker forgets state It was stopped when idle Store state in chrome.storage
"Refused to execute inline script" CSP See Content Security Policy
API is undefined Missing permission or wrong context Add it to permissions; check where the code runs

Debugging the service worker lifecycle

A worker stops after about 30 seconds without events. To test it, open chrome://serviceworker-internals (look for your extension id), or use the Application panel in the worker's DevTools to stop and start it. Make sure every top-level listener is registered synchronously when the script loads, and that your code survives a restart with no memory. Adding a chrome.runtime.onStartup log and an onInstalled log shows when the worker begins.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where do console.log calls from the service worker appear?

    Each context has its own DevTools. The service worker's is opened from the Inspect views link on chrome://extensions.
  2. 2. You edited content.js and reloaded the extension, but nothing changed on an open tab. What did you forget?

    Open pages keep the old content script until they are reloaded.
  3. 3. How can you run console code inside a content script's world?

    The console's JavaScript context selector lets you switch from the page to your extension's isolated world.
  4. 4. A popup closes before you can inspect it. What helps?

    chrome-extension://<id>/popup.html opens like any page, so DevTools stays open.

Summary

  • Load unpacked, reload the extension after changes and refresh pages for content script edits.
  • Debug each context in its own DevTools: worker, popup, options, content script.
  • The Errors button shows manifest, registration and runtime problems.
  • Tag logs by context, and test that the worker survives being stopped.

Next: Unit Testing Extension Code