From 0a02c50059fba4700c51dd2da25fe8e14008acee Mon Sep 17 00:00:00 2001
From: Mikael Brevik <mikaelbre@gmail.com>
Date: Fri, 9 Oct 2026 21:45:05 +0200
Subject: [PATCH] docs: adds troubleshooting for cron and services

---
 CHANGELOG.md |  1 +
 README.md    | 16 ++++++++++++++++
 2 files changed, 17 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3486cff..9c486b5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -26,6 +26,7 @@ Features:
 Fixes:
 
 - Windows: `WindowsToaster` now accepts `remove` without a `message`, the same as `close` ([#431](https://github.com/mikaelbr/node-notifier/issues/431)).
+- Docs: adds README troubleshooting for cron, PM2 and services ([#226](https://github.com/mikaelbr/node-notifier/issues/226), [#333](https://github.com/mikaelbr/node-notifier/issues/333)).
 - Windows: updates the bundled 64-bit SnoreToast to 0.9.1, so clicks and action buttons are reported back when using a custom `appID` ([#326](https://github.com/mikaelbr/node-notifier/issues/326), [#332](https://github.com/mikaelbr/node-notifier/issues/332), [#375](https://github.com/mikaelbr/node-notifier/pull/375)). The binary is KDE's own build of the official release. The 32-bit binary stays on 0.7.0, as KDE publishes no 32-bit build. Note that the new binary is not code-signed.
 - Windows: fixes `notify` throwing in `cluster` worker processes ([#410](https://github.com/mikaelbr/node-notifier/issues/410)).
 
diff --git a/README.md b/README.md
index 007bc4c..dddc702 100644
--- a/README.md
+++ b/README.md
@@ -506,6 +506,22 @@ point `customPath` to it.
 See [Issue #71 for more info](https://github.com/mikaelbr/node-notifier/issues/71)
 <https://github.com/mikaelbr/node-notifier/issues/71>.
 
+### Notifications from cron, PM2 or services
+
+Notifications are shown on the desktop of the logged-in user, so the process must run as that same user, while they are logged in.
+
+**Linux:** cron and some process managers start without the user's session environment, so `notify-send` can't reach the session bus. Set `XDG_RUNTIME_DIR`, and `DBUS_SESSION_BUS_ADDRESS` if that isn't enough. On a standard systemd user session they are:
+
+```sh
+* * * * * XDG_RUNTIME_DIR=/run/user/$(id -u) DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$(id -u)/bus node /path/to/app.js
+```
+
+With PM2, start it as the desktop user (not root), or set the same variables in its environment.
+
+**Windows:** services running as `SYSTEM` can't show notifications on the user's desktop. Set the service (or PM2) to log on as the logged-in user's account.
+
+See [#226](https://github.com/mikaelbr/node-notifier/issues/226) and [#333](https://github.com/mikaelbr/node-notifier/issues/333).
+
 ### Within Electron Packaging
 
 If packaging your Electron app as an `asar`, you will find `node-notifier` will fail to load.