Troubleshooting
Almost every “it doesn't work” report comes down to a caching plugin. Start with the two boxes below, or search for your symptom. This page is often faster than waiting for an email reply. Still stuck? Contact us.
No problems match that. Try another word, or contact us.
Exclude the plugin's script from JavaScript optimization
Caching plugins can combine, defer, or delay scripts and break the order this plugin needs. Add all three entries to every JavaScript exclusion list your caching plugin has.
WPPNsubscribe.js/wp-content/plugins/wp-push-notify/assets/js/subscribe.js- LiteSpeed Cache
- Page Optimization, then Tuning. Paste all three lines, one per line, into JS Excludes, JS Deferred / Delayed Excludes, and Guest Mode JS Excludes. Save, then purge all.
- WP Rocket
- File Optimization. Add
subscribe.jsto the excluded JavaScript boxes for minify, combine, deferred loading, and Delay JavaScript execution. - Autoptimize
- JavaScript Options, then Exclude scripts from Autoptimize.
- Any other caching plugin
- Look for “exclude JS”, “defer”, “delay”, and “combine” lists, and add the same entries to each.
Never cache these addresses
A cached copy of the service worker breaks subscribing. Add these to your caching plugin's “do not cache” list. The plugin already tells WP Rocket and W3 Total Cache, but LiteSpeed Cache needs them added by hand.
/wppn-sw.js/wppn-manifest.json/wp-json/wppn//wp-content/plugins/wp-push-notify/sw/wppn-worker.php- LiteSpeed Cache
- Cache, then Excludes, then Do Not Cache URIs. One address per line.
- After saving
- Purge everything, including your CDN. Then, on the device you test with, unregister the old service worker and subscribe again.
- Menu names
- Wording differs a little between plugin versions. Look for the same idea if a label isn't identical.
Nothing shows up
No popup, no bell, or a button that does nothing.
There's no popup, no bell, and the button does nothing
Why it happens. Prompt Style is set to Button only. In that mode nothing appears by itself.
The fix. In Push Notifications, Settings, choose Bell, Automatic, or Automatic + bell. Or place the [wppn_subscribe_button] shortcode on the page.
It works on one web address but not another
Why it happens. Browsers only allow push on a secure connection. If your certificate doesn't cover that exact address (www or non-www, a staging subdomain, an IP address), it fails there and works elsewhere.
The fix. Open each address you test and check the padlock. The certificate must cover that exact hostname.
The popup never appears in my own browser
Why it happens. Two common causes. The site's Notifications permission may already be Blocked, and browsers never ask again after a block. Or Chrome has quietly switched to quieter prompts after you dismissed several across all sites.
The fix. Click the padlock next to the address, find Notifications, and reset it. In Chrome, open chrome://settings/content/notifications and make sure it says Ask before sending.
It works in Incognito but not in my normal browser
Why it happens. Incognito starts clean. Your normal profile has old state from earlier testing: a stale service worker, a saved permission choice, cached files. Incognito isn't better; your profile is just carrying leftovers. (Some Chromium browsers also block the prompt entirely in private windows. The plugin shows a specific message when that happens.)
The fix. On desktop: DevTools, Application, Service Workers, Unregister. On Android Chrome: Site settings, Clear & reset. Then reload and try again.
Nothing happens on an iPhone or iPad
Why it happens. A regular Safari tab on iOS can't receive push from any site. This is an Apple limit, not something a plugin can change.
The fix. Add the site to the Home Screen (iOS 16.4 or later) and open it from there.
The “Add to Home Screen” install prompt is missing
Why it happens. Your site uses Plain permalinks. Push itself still works, but the install prompt needs the manifest file, and that relies on permalink rewrite rules.
The fix. Go to Settings, Permalinks, and choose any option except Plain. Also set a Site Icon under Settings, General. Without one the plugin falls back to its own bundled icon.
It works sometimes, but not always
The classic sign of a caching layer serving different visitors different versions of the page.
The console says WPPN is undefined, or the bell shows for some visitors only
Why it happens. A JavaScript optimizer (combine, defer, or delay) reordered subscribe.js so it runs before the small script that gives it its settings. It then silently does nothing.
The fix. Exclude subscribe.js from every JavaScript optimization list in your caching plugin, including Guest Mode lists. The exact entries and where to paste them are in the box at the top of this section.
Mobile and desktop visitors get different results
Why it happens. A “cache by device type” setting is only half configured in your caching plugin or CDN, so mobile visitors can be handed a desktop copy of the page, or the other way around.
The fix. Either set it up fully or turn it off, then purge everything, including your CDN.
After an update the old design still shows, or the “You're subscribed” tip looks like a tall black box
Why it happens. Your site is serving an old cached copy of the plugin's stylesheet or scripts, so the new version isn't actually running.
The fix. Make sure the latest plugin files are uploaded, then purge every cache: your caching plugin, your CDN (Cloudflare or similar), and the browser (hard refresh). The plugin purges the common cache plugins itself when you update, but a manual purge is still the right first step.
Subscribers or notifications are missing
Visitors say they subscribed, but the list is empty or nothing arrives.
The subscriber list is empty and no notification arrives
Why it happens. A caching plugin served an old or broken copy of the service worker address (wppn-sw.js). That one bad response breaks saving the subscriber and showing the thank-you popup at the same time.
The fix. Add the four addresses from the second box above to your cache plugin's “do not cache” list and purge everything. Then, on your test device, unregister the old service worker and subscribe again. Since v1.2.6 the plugin also sends no-cache signals and repairs its own route, but a cache that was already broken needs one manual purge.
The service worker or manifest returns 403 or 404
Why it happens. Either a security plugin quarantined the file (some flag double extensions like .js.php as malware, which is why the worker is named wppn-worker.php), or another plugin flushed WordPress's rewrite rules and dropped the plugin's route.
The fix. Check your security plugin's quarantine log and allow the file. For the route, open wp-admin and the plugin repairs it on the next page load, or go to Settings, Permalinks, and click Save Changes.
Notifications show up with no icon
Why it happens. Your site has no Site Icon set.
The fix. Set one under Settings, General. The plugin uses its own bundled icon until you do, and switches to yours automatically.
A big send stops partway through
Why it happens. Large sends run in the background through WP-Cron, and your host has WP-Cron switched off or it runs unreliably.
The fix. The plugin resumes a stalled send whenever anyone opens wp-admin, and warns you under Push Notifications, Advanced. For reliable timing, set up a real server cron job that calls wp-cron.php every few minutes.
Only 200 people received my notification
Why it happens. That's the Free plan limit: each notification reaches up to 200 subscribers.
The fix. Upgrade to Premium and the limit is gone.
A separate website can't subscribe to my site's push feed
Why it happens. The other site's address isn't on your allowed list, or it's written differently from how the browser sends it.
The fix. Under Advanced, Allowed external domains, enter it exactly as https://example.com: with the scheme, and with no trailing slash and no bare example.com.
My CSV import stopped before the end
Why it happens. A very large file hit your server's time limit.
The fix. Upload the same file again. The import is safe to repeat and carries on without creating duplicates.
License and updates
Trouble unlocking Premium, or after updating the plugin.
I bought Premium but I'm still limited to 200 subscribers
Why it happens. Either the Free version is still the one running, or the license hasn't been activated on this site yet.
The fix. On the Plugins page, make sure the Premium version is active (activating Premium switches Free off automatically). Then open the plugin's Account page from its menu and enter or activate your license key.
I see two WP Push Notify plugins in my list
Why it happens. Free and Premium are separate downloads. Activating Premium deactivates Free, but the Free copy stays in the list.
The fix. Confirm Premium is active first. Before deleting the Free copy, open Advanced and make sure the delete-data-on-uninstall option is turned off, so nothing is removed by accident. Then delete the Free copy.
Something looks wrong right after I updated
Why it happens. Almost always an old cached copy of the plugin's stylesheet or scripts, so the new version isn't really running yet.
The fix. Purge your caching plugin and your CDN, then hard-refresh. Each release on the updates page says if there's anything else to do.
Still stuck?
Two things show the real cause almost every time.
In the browser
Press F12, open the Console tab, and reload the page. Any line that starts with WPPN: says what went wrong. On a phone, connect it by USB and open chrome://inspect on a desktop Chrome to see the same console live.
On the server
Turn on Debug mode under Advanced, reproduce the problem, then open your PHP error log. Every failed send is logged with a [WP Push Notify] prefix and the exact status the push service returned.