Quick fixes for the issues that come up most often with MokoNtfy.
"Branding uploads are not enabled" when uploading an icon
Symptom: On Site Administration › Branding, uploading a logo or app icon fails with a message that branding uploads are not enabled on this server.
Cause: Icon/logo upload writes files to a directory on the server, which is disabled by default. Uploads stay inert until the operator configures a writable brand-asset directory.
Fix (operator): Set brand-asset-dir in the server config (or the NTFY_BRAND_ASSET_DIR environment variable) to a writable path and restart the server. With it unset, the Branding page still works for the config-driven brand settings — only file uploads are disabled.
Google login stuck on "pending approval"
Symptom: You sign in with Google but land in a pending state and can't use your account.
Cause: New accounts created via Sign in with Google can require administrator approval before they are active.
Fix: An admin or owner opens Site Administration › Google Approvals and approves (or rejects) the pending account. Once approved, sign in again.
Can't read or publish a topic (protected / deny-all)
Symptom: Subscribing or publishing to a topic is refused even though the topic name is correct.
Cause: The topic is protected (or otherwise not covered by the Everyone grant / default access). A protected topic is unreachable without an explicit grant — the fall-through Everyone grant and server default access no longer apply to it. A per-user deny also always wins over any group grant.
Fix: An admin/owner grants you (or a group you're in) explicit access in Site Administration › Access, e.g. read, write or read-write on that topic. If you have a per-user deny on the topic, that must be removed — it overrides group grants. Owners, admins and a topic's reservation owner always retain access. See Access Control & Roles.
Web-push notifications not arriving in the background
Symptom: Notifications show while the app is open but nothing arrives when it's closed.
Causes & fixes:
- Install the app. Background web push is most reliable from the installed PWA — use your browser's Install / Add to Home Screen option.
- Grant notification permission. The browser/OS must allow notifications for the site; check the site's notification permission and your OS notification settings.
- Browser/OS support. Web push depends on browser and OS support — on iOS in particular, web push only works from a home-screen-installed PWA on a recent iOS version, not from a Safari tab.
- Per-topic level. Confirm the topic isn't set to Muted or Important only (which suppresses non-priority messages) in the topic's menu.
Topics not loading
Symptom: The app opens but topics/notifications don't appear, or the list seems stuck.
Fixes:
- Force a refresh. The service worker auto-updates on deploy, but a hard reload (or closing and reopening the installed app) picks up a new version immediately.
- Check connectivity / sign-in. A dropped connection or an expired session can stall the live query; reload and, if needed, sign in again.
- Large history. Views load the most recent 1000 notifications for rendering, so a very large backlog no longer stalls startup — if it previously felt frozen, updating to the current release resolves it.
The welcome tour covers the screen or can't be dismissed
Symptom: The guided welcome tour appears but its popup — along with the Next/Skip buttons — is off-screen, or the page seems locked behind a dimmed overlay, especially on a narrow window or phone.
Cause: An older version could point a tour step at a control that wasn't currently on screen (for example an item inside the collapsed mobile menu), leaving the tour box and its Skip button outside the visible area.
Fix: Resolved in the current release — tour steps now only attach to controls that are actually visible, so the tour always stays on screen and can be dismissed. If you still hit it on an old tab, hard-refresh to load the latest version.