Electron migrated to UNNotification, and now your notifications silently fail unless the app is code-signed. Here's why — and how to fix it on your dev machine without packaging and signing on every run.
If you upgraded to Electron 42 and your macOS notifications suddenly stopped showing up, you're not doing anything wrong. The framework changed under your feet.
This is a hands-on guide. By the end you'll have:
- A tiny Electron app that sends notifications and shows a live history of every notification and the lifecycle events it emitted (
show,click,close,failed). - An understanding of why notifications fail with
UNErrorDomain error 1. - A free, one-time local code-signing setup so notifications work during
npm start— no packaging, no paid Apple Developer account.
The breaking change
From the Electron 42 release notes:
Behavior Changed: macOS notifications now use UNNotification API
Electron has migrated from the deprecatedNSUserNotificationAPI to theUNNotificationAPI on macOS. The new API requires that an application be code-signed in order for notifications to be displayed. If an application is not code-signed, notifications will emit afailedevent on theNotificationobject. (#47817)
Two consequences matter for everyday development:
- Code signing is now mandatory for a notification banner to appear on macOS.
-
Failures are silent unless you listen for them. When the app isn't properly signed, the
Notificationobject emits afailedevent instead of throwing. If you don't subscribe to it, nothing happens and nothing tells you why.
During local development you typically run npm start, which launches the unsigned Electron.app from node_modules. So every notification fails — quietly.
A test harness: notifications + history
Let's build the smallest possible app that makes the behavior visible. The Notification API lives in the main process, so the renderer drives it over IPC, and the main process records a history of every attempt and its events.
main.js
// Modules to control application life and create native browser window
const { app, BrowserWindow, Notification, ipcMain } = require('electron')
const path = require('node:path')
// In-memory log of every notification we've attempted, plus the lifecycle
// events each one emitted. On Electron 42+, macOS uses the UNNotification API
// which requires the app to be code-signed; unsigned builds emit a `failed`
// event instead of showing the banner. We record that here so it's visible.
const notificationHistory = []
let mainWindow = null
function pushHistoryEvent (id, type, detail) {
const entry = notificationHistory.find((n) => n.id === id)
if (!entry) return
entry.events.push({ type, detail: detail ?? null, at: new Date().toISOString() })
// Keep the renderer's history view in sync as events arrive.
if (mainWindow && !mainWindow.isDestroyed()) {
mainWindow.webContents.send('notification-history-updated', notificationHistory)
}
}
function showNotification (options = {}) {
const id = `${Date.now()}-${notificationHistory.length}`
const opts = {
title: options.title || 'Electron 42 notification',
body: options.body || 'Testing the UNNotification API on macOS.',
silent: Boolean(options.silent)
}
const entry = {
id,
options: opts,
supported: Notification.isSupported(),
createdAt: new Date().toISOString(),
events: []
}
notificationHistory.unshift(entry)
if (!entry.supported) {
pushHistoryEvent(id, 'unsupported', 'Notification.isSupported() returned false')
return { id, supported: false }
}
const notification = new Notification(opts)
notification.on('show', () => pushHistoryEvent(id, 'show'))
notification.on('click', () => pushHistoryEvent(id, 'click'))
notification.on('close', () => pushHistoryEvent(id, 'close'))
// The key Electron 42 macOS behavior: unsigned apps can't display
// notifications via UNNotification and emit `failed` with an error string.
notification.on('failed', (_event, error) => pushHistoryEvent(id, 'failed', String(error)))
notification.show()
return { id, supported: true }
}
function createWindow () {
mainWindow = new BrowserWindow({
width: 800,
height: 600,
webPreferences: {
preload: path.join(__dirname, 'preload.js')
}
})
mainWindow.loadFile('index.html')
}
app.whenReady().then(() => {
// IPC: send a notification and report whether it was supported.
ipcMain.handle('show-notification', (_event, options) => showNotification(options))
// IPC: hand the full attempt-and-event log back to the renderer.
ipcMain.handle('get-notification-history', () => notificationHistory)
createWindow()
app.on('activate', function () {
if (BrowserWindow.getAllWindows().length === 0) createWindow()
})
})
app.on('window-all-closed', function () {
if (process.platform !== 'darwin') app.quit()
})
A note on the word history: Electron does not expose the macOS Notification Center's system-wide history. What we track here is the app's own log of attempts and their events — which is exactly what you need to debug the signing problem, because the failed event shows up right in the list.
preload.js
The renderer has no direct access to the Notification module, so we expose a small, safe bridge over contextBridge:
const { contextBridge, ipcRenderer } = require('electron')
// Expose a minimal, safe notification API to the renderer. The Notification
// module lives in the main process, so the renderer drives it over IPC.
contextBridge.exposeInMainWorld('notifications', {
show: (options) => ipcRenderer.invoke('show-notification', options),
getHistory: () => ipcRenderer.invoke('get-notification-history'),
onHistoryUpdated: (callback) =>
ipcRenderer.on('notification-history-updated', (_event, history) => callback(history))
})
index.html
A simple form plus a history list:
<section id="notification-tester">
<h2>Notification tester</h2>
<label>Title <input id="notif-title" type="text" value="Electron 42 notification"></label>
<label>Body <input id="notif-body" type="text" value="Testing the UNNotification API on macOS."></label>
<label><input id="notif-silent" type="checkbox"> Silent</label>
<button id="send-notification" type="button">Send notification</button>
<h3>History</h3>
<ul id="notification-history"></ul>
</section>
<script src="./renderer.js"></script>
renderer.js
Wire the button and render the history, updating live as events arrive:
const historyList = document.getElementById('notification-history')
function renderHistory (history) {
if (!history || history.length === 0) {
historyList.innerHTML = '<li class="empty">No notifications sent yet.</li>'
return
}
historyList.innerHTML = ''
for (const entry of history) {
const item = document.createElement('li')
const title = document.createElement('div')
title.className = 'notif-title'
title.textContent = entry.options.title
item.appendChild(title)
const meta = document.createElement('div')
meta.className = 'notif-meta'
const events = entry.events.length
? entry.events.map((e) => (e.detail ? `${e.type} (${e.detail})` : e.type)).join(' → ')
: 'no events yet'
meta.textContent = `supported: ${entry.supported} · ${events}`
item.appendChild(meta)
historyList.appendChild(item)
}
}
async function refreshHistory () {
renderHistory(await window.notifications.getHistory())
}
document.getElementById('send-notification').addEventListener('click', async () => {
await window.notifications.show({
title: document.getElementById('notif-title').value,
body: document.getElementById('notif-body').value,
silent: document.getElementById('notif-silent').checked
})
refreshHistory()
})
// Live updates as the main process records show/click/close/failed events.
window.notifications.onHistoryUpdated(renderHistory)
document.addEventListener('DOMContentLoaded', refreshHistory)
Reproducing the failure
Run the unsigned dev app:
npm start
Click Send notification. No banner appears, and the history shows something like:
Electron 42 notification
supported: true · failed (The operation couldn't be completed. (UNErrorDomain error 1.))
Notice supported: true. Notification.isSupported() returns true because the API is available — but the actual display fails. That's the whole trap: support and delivery are now two different things.
UNErrorDomain error 1 is UNErrorCodeNotificationsNotAllowed. The UNNotification API refused to display the notification because the running app isn't code-signed.
Why ad-hoc signing isn't enough
You might reach for the quickest fix:
codesign --force --deep --sign - node_modules/electron/dist/Electron.app
If you inspect the bundle Electron ships with, you'll see it already carries a signature:
codesign -dv node_modules/electron/dist/Electron.app
# ... flags=0x20002(adhoc,linker-signed) ...
That linker-signed flag is the catch. It's an automatic signature the linker applies — UNNotification does not accept it. A real ad-hoc signature (codesign --sign -) drops the linker-signed flag:
codesign -dv node_modules/electron/dist/Electron.app
# ... flags=0x2(adhoc) ...
This does make notifications work. But ad-hoc signing has a serious drawback for daily development, which leads to the next problem.
The Keychain prompt: why a stable identity matters
After re-signing, the next launch pops up a dialog:
Electron wants to use your confidential information stored in "Electron Safe Storage" in your keychain.
This isn't from our notification code. Under the hood, Electron is Chromium, and Chromium stores an encryption key (for cookies and the safeStorage API) in the macOS Keychain under "Electron Safe Storage". Access to a Keychain item is gated by the app's code signature. When you re-sign the app, macOS sees a different identity and asks for permission again.
Here's the trap with ad-hoc signatures: they have no stable identity. Every codesign --sign - produces a new cdhash. So even if you click Always Allow, the next re-sign (say, after npm install) invalidates the Keychain ACL and the prompt returns.
The fix is to sign with a stable identity — a real certificate. Then Always Allow sticks forever, and notifications keep working across reinstalls.
You don't need a paid Apple Developer account for this. A free, self-signed code-signing certificate is enough for local development.
The fix: a free self-signed code-signing certificate
Option A — Keychain Access (GUI)
- Open Keychain Access.
- Menu: Keychain Access → Certificate Assistant → Create a Certificate…
- Name:
Electron Dev. Identity Type: Self-Signed Root. Certificate Type: Code Signing. - Create it. It lands in your login keychain, ready to use.
Option B — Command line
If you prefer to script it, generate the key and certificate with OpenSSL, import it, and trust it for code signing:
# 1. Generate a self-signed code-signing certificate
cat > /tmp/electron-dev-cert.conf <<'EOF'
[ req ]
distinguished_name = dn
x509_extensions = ext
prompt = no
[ dn ]
CN = Electron Dev
[ ext ]
keyUsage = critical, digitalSignature
extendedKeyUsage = critical, codeSigning
basicConstraints = critical, CA:false
EOF
openssl req -x509 -newkey rsa:2048 \
-keyout /tmp/electron-dev-key.pem -out /tmp/electron-dev-cert.pem \
-days 3650 -nodes -config /tmp/electron-dev-cert.conf
# 2. Bundle into a .p12. Use legacy algorithms + a non-empty password,
# otherwise macOS `security` fails with "MAC verification failed".
openssl pkcs12 -export -legacy -macalg sha1 \
-inkey /tmp/electron-dev-key.pem -in /tmp/electron-dev-cert.pem \
-out /tmp/electron-dev.p12 -passout pass:electron -name "Electron Dev"
# 3. Import into the login keychain, allowing codesign to use the key
security import /tmp/electron-dev.p12 \
-k ~/Library/Keychains/login.keychain-db \
-P "electron" -T /usr/bin/codesign
# 4. Trust the certificate for code signing
# (macOS will prompt for your login password — approve it)
security add-trusted-cert -r trustRoot -p codeSign \
-k ~/Library/Keychains/login.keychain-db /tmp/electron-dev-cert.pem
# 5. Clean up the private key material on disk — it lives safely in the keychain now
rm -f /tmp/electron-dev-key.pem /tmp/electron-dev.p12 \
/tmp/electron-dev-cert.pem /tmp/electron-dev-cert.conf
⚠️ Two gotchas the recipe above already handles:
- Empty p12 passwords fail to import on recent macOS. Use a non-empty
-passout/-Ppair.- OpenSSL 3 defaults are incompatible with the macOS
securitytool. Add-legacy -macalg sha1when exporting the p12, or you'll hitMAC verification failed during PKCS12 import (wrong password?).
Verify the identity is now valid:
security find-identity -v -p codesigning
# 1) 7495...CB11 "Electron Dev"
Sign the dev binary and automate it
Sign the Electron.app that npm start actually runs:
codesign --force --deep --sign "Electron Dev" node_modules/electron/dist/Electron.app
Confirm the result — note Authority=Electron Dev and flags=0x0(none) (no more linker-signed):
codesign -dvv node_modules/electron/dist/Electron.app
# Authority=Electron Dev
# flags=0x0(none)
The signature is lost every time Electron is reinstalled, so wire it into package.json so it re-applies automatically:
{
"scripts": {
"start": "electron .",
"sign:dev": "codesign --force --deep --sign \"Electron Dev\" node_modules/electron/dist/Electron.app",
"postinstall": "node -e \"process.platform==='darwin' && require('child_process').execSync('npm run sign:dev', {stdio: 'inherit'})\""
}
}
-
npm run sign:dev— re-sign on demand. -
postinstall— re-sign automatically after everynpm install, and only on macOS (it's a no-op elsewhere, so it won't break Linux/Windows teammates).
Verify
npm start
Click Send notification. This time:
- A notification banner appears.
- The history shows
supported: true · show(andclick/closeas you interact).
The Keychain prompt appears once more (because the signature changed from the previous run). Click Always Allow — and because the Electron Dev identity is now stable, it's remembered for good, surviving future npm install and npm run sign:dev runs.
You can find the complete code on GitHub.
Good luck and have fun!
