Chrome Extension Error Tracking: Catching Service Worker Errors in Production
7 min readModerok team
Chrome extension error tracking in Manifest V3: why production errors are invisible, which contexts need their own handler, and what to send.
Nothing reports your extension's production errors to you. Chrome records runtime errors on the Extensions Management page, but that is the browser you are sitting in front of, not the installs out in the world. The Chrome Web Store developer dashboard reports installs, impressions and users, and no error data at all. Chrome extension error tracking in Manifest V3 therefore means one thing: registering error and unhandledrejection handlers at the top level of every context you ship, and sending what they catch to an endpoint you control.
TL;DR: Chrome surfaces extension errors only locally, in
chrome://extensions. The Web Store dashboard has no error reporting. To see production errors you register global handlers at the top level of each extension context (they do not share a JavaScript realm), capturechrome.runtime.lastErrorandtry/catchbranches explicitly because no global handler fires for them, and send reports immediately rather than buffering, because Chrome terminates the service worker after 30 seconds of inactivity.
Why production errors never reach you
Chrome's own debugging tutorial is explicit about where extension errors go. On the Extensions Management page, "The Errors button label turns red when there's an error," and "only runtime errors, console.warning and, console.error are recorded on the Extensions Management page" (Chrome for Developers). The same page tells you to "click Clear all in the upper right-hand corner to clear the logs, and reload the extension" (Chrome for Developers). It is a debugging aid, not telemetry.
The store side gives you nothing either. Chrome's metrics documentation describes four reporting areas for an item: installs and uninstalls, impressions, users, and an optional opt-in analytics property for store-listing traffic (Chrome for Developers). Of the Users section it notes that it "only captures installations" rather than activity. No area covers runtime errors, crashes or exceptions. A regression that throws on every startup produces the same dashboard as a healthy release, until the reviews arrive.
Error tracking needs a handler per context
The most common mistake is wiring a handler in the service worker and calling it done. An MV3 extension ships several independent JavaScript realms, and an uncaught throw in one is invisible to the others:
- The background service worker.
- Extension pages: the popup, the options page, a side panel, anything of yours loaded in a tab.
- Content scripts, which run in the page rather than in your extension. Chrome's debug page says "Content scripts run inside a website" and that to find those errors "we must inspect the web page the extension is trying to alter" (Chrome for Developers).
- Offscreen documents, if you use one for DOM work.
Each needs its own registration. A popup that throws while rendering will not appear in the service worker's handler, and the popup's console closes with the popup.
Register the handler at the top level, synchronously
Chrome's service worker events page is unambiguous about placement: "Event handlers in service workers need to be declared in the global scope," "they should be at the top level of the script and not be nested inside functions," and "This ensures that they are registered synchronously on initial script execution" (Chrome for Developers). That page labels a listener nested inside a storage.local.get callback as "Not advised" (Chrome for Developers).
The rule applies to your error handler too, and for a sharper reason: a worker that is woken by an event and throws during startup throws before any handler you registered inside an await block exists.
// background.js, top level, before any await
// report() is yours to implement: POST the payload to your own
// endpoint, or hand it to an analytics SDK.
async function report(payload) { /* ... */ }
self.addEventListener("error", (event) => {
report({
kind: "uncaught_exception",
message: event.message,
filename: event.filename,
line: event.lineno,
});
});
self.addEventListener("unhandledrejection", (event) => {
const reason = event.reason;
report({
kind: "unhandled_rejection",
message: reason instanceof Error ? reason.message : String(reason),
stack: reason instanceof Error ? reason.stack : undefined,
});
});
One caveat. MDN documents both events on WorkerGlobalScope: the error event "fires when an error occurs in the worker", and the unhandledrejection event "is sent to the global scope (typically WorkerGlobalScope) of a script when a Promise that has no rejection handler is rejected". ServiceWorkerGlobalScope "inherits from the WorkerGlobalScope interface, and its parent EventTarget", but its own reference page does not list a generic error event. Treat the global handler as your baseline rather than your only net, and verify it fires in your own build.
The errors no global handler will ever see
Three large categories never reach self.addEventListener("error"):
chrome.runtime.lastError. Callback-style Chrome APIs do not throw on failure. The runtime reference says the property is "Populated with an error message if calling an API function fails; otherwise undefined," and that "This is only defined within the scope of that function's callback" (Chrome for Developers). If you never read it, the docs say only that "a message is logged to the console listing the API function that produced the error" (Chrome for Developers). A console line in a browser you cannot see is not a report. We went through the failure modes in detail in catching chrome.runtime.lastError.
Anything you caught. A try/catch around a network call is correct code, and it makes the error invisible unless the catch block reports it.
console.error. It is recorded on the Extensions Management page locally, and it goes nowhere else.
Service worker termination is what breaks homemade reporters
Chrome terminates the service worker "After 30 seconds of inactivity. Receiving an event or calling an extension API resets this timer," and also kills a single request running past five minutes or a fetch() whose response takes longer than 30 seconds (Chrome for Developers). The same page advises that "you should design your service worker to be resilient against unexpected termination."
For an error reporter this is the whole design problem. A reporter that accumulates errors in a module-level array and flushes every minute loses the array on every shutdown, and shutdown is the normal case, not the exception. Worse, the error that killed your startup path is exactly the one least likely to survive a buffer. Anything you want to keep goes through chrome.storage.local, and anything you can send now, you send now.
You cannot load a reporter from a CDN
A service worker has no document to append a script tag to, and MV3 closes the door from the policy side as well. Chrome's security migration page states the rule: "In Manifest V3, all of your extension's logic must be part of the extension package," and lists "Any library hosted on a CDN" and "Bundled third-party libraries that dynamically fetch remote hosted code" among the things that are not allowed (Chrome for Developers). Whatever reporter you pick has to be a bundled module that does not fetch code at runtime.
What belongs in an error report
Enough to triage, and nothing about the person. Message, stack, whether the error was handled, a fingerprint so repeats collapse, your extension version, and the browser and OS. Never the URL of the page the user was on, never form contents, never anything pulled out of a page. The boundary is the same one we drew in what to track in a Chrome extension: an error payload assembled from a page is user data, and collecting it brings the Web Store's disclosure duties with it.
Then dedupe before you send. An error inside a storage.onChanged or onMessage handler fires once per event, and events arrive in bursts, so an unthrottled reporter turns one bug into a request flood.
What the Moderok SDK does here
Error capture is on by default in @moderok/sdk: in every context where you call Moderok.init(), uncaught exceptions and unhandled rejections are recorded as __error events. Moderok.captureError(error, props) handles your catch blocks, Moderok.captureLastError(apiName, chrome.runtime.lastError, props) handles callback failures, and captureConsoleErrors: true mirrors console.error when you want the noise. Set trackErrors: false to opt a context out.
The limits are in the source, not in marketing copy: error events are fingerprinted and a repeat of the same fingerprint inside a 60 second window is dropped, no more than 20 error events are sent per 60 second window, messages truncate at 500 characters and stacks at 1,800, and any single event over 8 KiB is rejected by the queue. The queue is capped, debounced, and persists retryable failures with backoff, so expect loss under sustained failure rather than zero loss. The SDK is 5.7 kB gzipped with zero runtime dependencies and needs no host_permissions.
Setup is three parts: install @moderok/sdk, add the storage permission, and call Moderok.init() at the top of each context you want covered. Errors land in the dashboard's Logs view, which has an explicit Refresh action, alongside installs, actives and your custom events (see the dashboard). Start with the error tracking guide.