Deep Dive · 6 min read
Chrome Extension Debugging Guide
Where each part of an extension logs, how to open the right DevTools window, and the errors that catch everyone out.
Extensions are confusing to debug because each surface runs in its own context with its own console. Once you know which DevTools window to open, most bugs take minutes.
Three consoles, three surfaces
- Popup — right-click the toolbar icon and choose 'Inspect popup'.
- Service worker — open chrome://extensions and click the 'service worker' link on your extension card.
- Content script — use the normal page DevTools; your logs appear alongside the site's, filtered by the extension context selector.
Read the Errors panel first
On chrome://extensions, a red Errors button appears whenever loading or the service worker fails. It shows the file and line, which beats guessing.
Errors that catch everyone
- 'Refused to execute inline script' — MV3 CSP; move the code into an external file.
- 'Cannot access contents of the page' — missing host_permissions or activeTab.
- 'Extension context invalidated' — the extension reloaded while a content script was still running; refresh the page.
- 'Receiving end does not exist' — you messaged a tab with no content script injected yet.
- Service worker logs disappearing — the worker went idle; re-open the inspector or use chrome.storage for durable traces.
A quick triage order
- Does the extension load without a manifest error?
- Does the service worker register and stay error-free?
- Does the popup render and log?
- Is the content script injected on the URL you are testing?
- Are permissions granted for the API you are calling?
Frequently asked questions
Why do my console.log lines vanish in the service worker?
MV3 workers shut down after ~30 seconds of inactivity and the inspector detaches. Re-open the service worker inspector or persist logs to chrome.storage.local.