Fix chrome.notifications.create not showing a notification in MV3
6 min readModerok team
Why chrome.notifications.create silently shows nothing in a Manifest V3 extension, the manifest and iconUrl fix, and what still breaks after it.
If chrome.notifications.create is not working in your Manifest V3 extension, the call is almost certainly failing before Chrome gets a chance to draw anything, and the two usual reasons are a missing notifications permission and an iconUrl that does not resolve. Declare the permission, pass all four required options, build the icon path with chrome.runtime.getURL(), and await the promise so failures surface:
{
"manifest_version": 3,
"name": "My Extension",
"version": "1.0.0",
"permissions": ["notifications"],
"background": { "service_worker": "background.js", "type": "module" }
}
// background.js
async function notify(message) {
try {
const id = await chrome.notifications.create({
type: "basic",
iconUrl: chrome.runtime.getURL("icons/128.png"),
title: "Sync finished",
message,
});
console.log("shown", id);
} catch (err) {
console.error("notifications.create failed", err);
}
}
Chrome's permissions list describes notifications as "Gives access to the chrome.notifications API" (Chrome for Developers), so check the manifest before you start debugging the options.
Why chrome.notifications.create shows nothing and logs nothing
What makes this hard to debug is that the image fetch happens in the renderer-side bindings, before the request reaches the browser process. Chromium's notifications bindings collect an image request for iconUrl, imageUrl, appIconMaskUrl and each button's iconUrl, load them all, then branch:
replaceNotificationOptionURLs(notification_details_copy, function(success) {
if (success) {
bindingUtil.sendRequest(
name, [id, notification_details_copy, success_callback], undefined);
return;
}
failure_callback('Unable to download all specified images.');
});
That is notifications_custom_bindings.js in the Chromium tree (chromium.googlesource.com), and the same generateHandler is registered for both create and update. If one image fails to load, sendRequest is never called. The notification is not delayed or drawn without an icon, it never happens, and the only trace is the string Unable to download all specified images.
Where that string ends up decides whether you see it. In the promise form it is a rejection, which a bare chrome.notifications.create({...}) with no await and no .catch() never surfaces where you are looking. In the callback form it lands in chrome.runtime.lastError, which neither throws nor stops execution, the same trap described in catching chrome.runtime.lastError in MV3.
A path that looks right can still fail. Chrome says icon URLs "can be a data URL, a blob URL, or a URL relative to a resource within this extension's .crx file" (Chrome for Developers), which leaves you reasoning about what a relative string is relative to, a worse question when a bundler emits the worker into a subdirectory. chrome.runtime.getURL() takes that question away: it "Converts a relative path within an app/extension install directory to a fully-qualified URL" (Chrome for Developers).
The four options that are not optional
Chrome's reference marks four NotificationOptions properties as required for create(): type, iconUrl, title and message. On each of the last three the page prints the same note: "This value is required for the notifications.create() method" (Chrome for Developers). iconUrl is the one that hurts: required, and the only one of the four that can fail in the image loader above when it is present but unresolvable.
When the user has turned you off
If the call succeeds and nothing appears, check the permission level. notifications.getPermissionLevel() "Retrieves whether the user has enabled notifications from this app or extension" and returns either granted, which the reference calls the default at install time, or denied, which "Specifies that the user has elected not to show notifications from the app or extension" (Chrome for Developers).
const level = await chrome.notifications.getPermissionLevel();
if (level === "denied") return; // nothing you pass will be drawn
priority is a second filter. The reference's description of that property reads "Priority ranges from -2 to 2. -2 is lowest priority. 2 is highest. Zero is default. On platforms that don't support a notification center (Windows, Linux & Mac), -2 and -1 result in an error as notifications with those priorities will not be shown at all" (Chrome for Developers). If you lowered the priority to be polite, raise it to 0.
Past that, "the details of how notifications appear and behave may differ according to the operating system and the user's settings" (MDN).
The constant id that eats your notifications
If the first notification shows and later ones do not, look at the id. Chrome documents that for create() the identifier "If not set or empty, an ID will automatically be generated", that an id matching an existing notification clears that one first, and that it may not exceed 500 characters (Chrome for Developers). A hardcoded "status" id is a replace-in-place, not a queue. Pass no id when each message should stand on its own.
Clicks need a top-level listener, not a callback
Showing the notification is the easy half. The worker that created it can be gone when someone clicks, so the click arrives at a freshly started worker and the listener has to exist during that startup. Chrome's events guide is explicit: "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, which enables Chrome to dispatch events to the service worker as soon as it starts" (Chrome for Developers).
// top level of background.js, not inside notify()
chrome.notifications.onClicked.addListener((notificationId) => {
chrome.tabs.create({ url: chrome.runtime.getURL("options.html") });
});
Chrome's reference lists onButtonClicked, onClicked, onClosed, onPermissionLevelChanged and onShowSettings, the last deprecated since Chrome 65. There is no onShown, so you cannot confirm display from the extension side. onClicked fires when "The user clicked in a non-button area of the notification" (Chrome for Developers).
One more MV3 trap: the web Notification constructor is not a way out. MDN lists "The constructor is called within the ServiceWorkerGlobalScope" as a TypeError condition (MDN). Its suggested alternative, ServiceWorkerRegistration.showNotification(), is marked "available in Web Workers", but that is the web notifications API; the options and events described here belong to chrome.notifications, which is what an MV3 background worker should use.
What still breaks after the fix
Several fields are documented as deprecated or ineffective, and they fail quietly. isClickable is "ignored as of Chrome 67", while appIconMaskUrl and imageUrl are deprecated since Chrome 59, and button icons are deprecated since Chrome 59 and not visible to Mac OS X users (Chrome for Developers). Button icons and appIconMaskUrl still go through the same image loader, so a broken path in a deprecated field can still cost you the whole notification.
The permission is also not free at install time: Chrome's permissions list prints "Warning displayed: Display notifications." for it, while the storage entry carries no warning text (Chrome for Developers).
Firefox differences
Firefox implements the same API, which MDN notes "is based on Chromium's chrome.notifications API", but with a smaller option surface. Its NotificationOptions page states that "Firefox currently: only supports the type, title, message, and iconUrl properties; and the only supported value for type is 'basic'", and adds that "appIconMaskUrl and isClickable are not supported" (MDN). A list or progress notification with buttons is therefore not portable, and since buttons is outside that set, an onButtonClicked handler has nothing to fire on. MDN's notifications page documents an onShown event, "Fired immediately after a notification has been shown", which Chrome's reference does not list, so treat it as optional in shared code. Firefox's background script is an event page, not a service worker (Firefox MV3 event pages vs service workers), but the top-level listener discipline is the same.
Knowing it failed in production
Locally you can read the rejection in the worker console. On a user's machine you cannot, and a notification that never drew is the kind of failure nobody files a bug about. The callback path is the one to wire up by hand, because chrome.runtime.lastError throws nothing for a global handler to catch. The Moderok SDK takes it as Moderok.captureLastError("notifications.create", chrome.runtime.lastError) and assembles the event from the API name and the message itself, and its docs state the SDK records unhandled promise rejections on its own, which covers the unawaited create(). Read the counts as a signal, not a census: identical errors are deduped inside a 60 second window and error events are capped at 20 per minute. The error tracking guide has the handler shapes.