WordPress troubleshooting

Comprehensive guide for troubleshooting common setup issues with OneSignal Web Push Notifications on WordPress, including browser compatibility (Chrome, Firefox, Safari), plugin integration, and resolving CDN or caching conflicts.

Common setup issues

Verify your OneSignal dashboard setup

Make sure you’ve completed each step in the WordPress setup guide:

• Select the WordPress Plugin option when creating your OneSignal app
• Your Site URL must exactly match the browser URL
  • For example, https://example.com is not the same as https://www.example.com. Use one version consistently.
  • Only one site origin is supported for push. See Same-origin policy.
• Make sure you’ve added at least one permission prompt.

Do not add the OneSignal code manually

The OneSignal WordPress plugin automatically includes the initialization script and Service Worker.

• Do not add OneSignal JavaScript init code to your site.
• Do not use the Custom Code Setup with the WordPress plugin. If you need to customize the init method, uninstall the plugin and add the code and Service Worker manually.

Send notification when post published

When you publish a post, page, or custom post type, OneSignal can automatically send a notification to your subscribers.

OneSignal Push Notifications metabox—drag to reposition if needed

If you do not see the Send notification when post is published or updated checkbox, check these items:

1. Check the metaboxes to the right and bottom of the editor. You can drag and drop as needed.
2. Check the Screen Options at the top of the editor to make sure the OneSignal Push Notifications metabox is checked.

Screen Options showing OneSignal Push Notifications metabox checked

3. Check if using a Custom Post Type. This is usually found in the URL as post_type=your_custom_type. If so, add the custom post type to the Custom Post Types field in the OneSignal WordPress plugin settings.

Example where to find the custom post type name

---

How to troubleshoot your site

1. Verify plugin is active and open developer tools

   Load your site in a normal (non-incognito) browser window with the plugin enabled.

   

   Right-click your site, click Inspect, and open the Console tab.

2. Check the console for OneSignal errors

   Open the Console tab, refresh the page, and look for any red or yellow OneSignal-related errors. See Common OneSignal console errors for help.

3. Check subscription status in the browser

   After the page finishes loading and you see no OneSignal errors in the Console, paste:

   JavaScript

   OneSignal.User.PushSubscription.id
   

   If the visitor is subscribed, this returns a string (the Subscription ID). If they are not subscribed or the subscription is not ready yet, you may see null or an empty value. If you see OneSignal is not defined, wait a few seconds and try again, or fix Console errors from Common OneSignal console errors first—the SDK may still be loading via the deferred loader.

   

   Find your OneSignal Subscription ID in the console.

4. Verify Subscription ID in OneSignal dashboard

   In the OneSignal dashboard, go to Audience > Subscriptions and search for the ID returned above.

   

   Search your OneSignal dashboard for the Subscription ID.

5. Send a test push notification

   If the subscription exists and status is Subscribed, follow the Push guide to send a notification. If nothing appears, see Notifications not shown for browser-specific fixes.

---

Common OneSignal console errors

SdkInitError: OneSignal: This web push config can only be used on … Your current origin is …

Site URL mismatch error.

Your site URL in the OneSignal dashboard doesn’t match your actual domain. Make sure it exactly matches the domain you see in the browser.

PushPermissionNotGrantedError: The user dismissed the permission prompt.

The visitor declined the browser prompt. It won’t appear again until a cooldown period expires. See Web permission prompts for browser rules or clear site data to retry immediately.

The OneSignal web SDK can only be initialized once.

Duplicate OneSignal initialization error.

You’re loading OneSignal twice. Remove manually added OneSignal code if you’re using the plugin.

Installing service worker failed.. 403 or 404 error

Service Worker file missing (403/404).

Make sure this file is accessible (replace your-site.com and match your actual plugin folder name if it differs from the default):

https://your-site.com/wp-content/plugins/onesignal-free-web-push-notifications/sdk_files/OneSignalSDKWorker.js

If not, see Common plugin support to fix CDN or caching issues.

---

Common plugin support

CDNs and caching plugins can block OneSignal’s required files. Paths below assume the plugin directory is onesignal-free-web-push-notifications; adjust if your install uses a different folder name.

Use these plugin-specific settings:

Autoptimize

In Excluded scripts, add:

wp-content/plugins/onesignal-free-web-push-notifications/sdk_files/(.*)

WP Rocket

Under CDN > Exclude Files From CDN, add:

(.*)/onesignal-free-web-push-notifications/sdk_files/(.*)

LiteSpeed Cache

Under CDN > Exclude Path, add:

(.*)/onesignal-free-web-push-notifications/sdk_files/(.*)

Then press save.

WP Super Cache

1. Go to Settings > WP Super Cache > CDN
2. In Exclude if substring, include: onesignal-free-web-push-notifications
3. Click Contents > Delete Cache

WP Engine

WP Engine can rewrite plugin URLs through its CDN. HTML Post-Processing rules are environment-specific; the snippet below is an example only—confirm paths with WP Engine support or your User Portal before applying.

In the WP Engine plugin > General Settings > HTML Post-Processing, you may need rules similar to the following. Replace every placeholder with values from your site and WP Engine CDN hostname:

Placeholder	Replace with
YOURSITEHERE	Your bare domain (regex segment), e.g. example for example.com
mywpenginehandleHere	Your WP Engine install name (subdomain before .wpengine.com)
wpengineCDNpathHere	Your NetDNA / CDN path segment from WP Engine (often shown in CDN URLs)
mywebsiteHere	Your live site origin without path, e.g. https://example.com

#https?://(www\.)?(YOURSITEHERE\.com|mywpenginehandleHere.wpengine.com|wpengineCDNpathHere.wpengine.netdna-(ssl|cdn).com)/wp-(content|includes)#
=> https://wpengineCDNpathHere-wpengine.netdna-ssl.com/wp-$4
#https://wpengineCDNpathHere-wpengine.netdna-ssl.com/plugins/onesignal-free-web-push-notifications/#
=> https://mywebsiteHere.com/wp-content/plugins/onesignal-free-web-push-notifications/
#https://wpengineCDNpathHere-wpengine.netdna-ssl.com/wp-content/plugins/onesignal-free-web-push-notifications/#
=> https://mywebsiteHere.com/wp-content/plugins/onesignal-free-web-push-notifications/

W3 Total Cache

1. Go to Performance > CDN
2. Under Rejected files, add:

{plugins_dir}/onesignal-free-web-push-notifications/sdk_files/*

W3 Total Cache exclusion settings.

BunnyCDN

Exclude onesignal in the plugin’s CDN Excluded Paths.

BunnyCDN exclusion example.

CDN Enabler

In Settings > CDN Enabler, add this to “Exclusions”:

onesignal-free-web-push-notifications

PressCDN

In Exclude Directories, add:

/wp-content/plugins/onesignal-free-web-push-notifications/

Breeze

In Settings > CDN > Exclude Content, add:

/onesignal-free-web-push-notifications/sdk_files/

Breeze exclusion example.

Hummingbird Pro

Go to Hummingbird > Asset Optimization. Under JavaScript (and CSS if OneSignal assets appear there), locate files whose URLs contain onesignal-free-web-push-notifications or OneSignalSDK. Exclude them from minification/combination/defer, or switch those assets to Don’t load optimization so the plugin does not rewrite or delay them.

Hummingbird Pro Asset Optimization.

Sucuri

Follow Sucuri’s Whitelist guide to allow OneSignal files.

Solid Security (formerly iThemes Security)

Disable Disable PHP in Plugins (or equivalent) under System Tweaks so OneSignalSDKWorker.js.php can run.

Disable blocking PHP execution in plugins for OneSignal.

Defender Security plugin

Do not enable “Prevent PHP execution”. Go to Defender Plugin > Security Tweaks and verify the setting is disabled.

Example .htaccess for Service Worker access

<Files *.php>
Order allow,deny
Deny from all
</Files>
<Files OneSignalSDKWorker.js.php>
Allow from all
ForceType 'application/javascript; charset=UTF-8'
</Files>
<Files OneSignalSDKWorker.js>
Allow from all
ForceType 'application/javascript; charset=UTF-8'
</Files>

Apache 2.4+ often uses Require all denied / Require all granted instead of Order allow,deny. Ask your host or adjust the rules to match your server’s Apache version.

---

Server slowdowns or site unreachable after sending notifications

If your server experiences slowdowns or becomes unreachable after sending notifications, it is often due to increased load from notification assets or limited server resources.

Do not host your own notification icons

Avoid self-hosting images used in notifications. When you host your own notification icons or images, your server may become overloaded as every recipient’s browser attempts to fetch the image at the same time a notification is sent. To reduce server strain, use image hosting solutions or CDN services optimized for high-concurrency access.

Consider upgrading hosting resources

If server issues persist, you may need to:

• Upgrade your hosting plan: Higher bandwidth or more powerful hosting may be necessary to handle large-scale notification sends.
• Consult your hosting provider: Your provider can offer insights or optimizations specific to your hosting environment.

---