​
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. ✅ This means:
  • You should not manually add OneSignal JavaScript code in your theme, footer, or other plugins.
❌ If you want to use Custom Code Setup, uninstall the WordPress plugin first to avoid conflicts.

​
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

Paste this in the console:
OneSignal.User.PushSubscription.id
If subscribed, it returns a string (your Subscription ID).

Find your OneSignal Subscription ID in the console.

4

Verify Subscription ID in OneSignal dashboard

Go to OneSignal.com > 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: 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. 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

In WP Engine plugin > General Settings > HTML Post-Processing, add these, replacing YOURSITEHERE:
text
#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 Asset Optimization, find the OneSignal SDK file, and remove it from optimization.

Hummingbird Pro Asset Optimization.

​
Sucuri

Follow Sucuri’s Whitelist guide to allow OneSignal files.

​
iThemes Security plugin

Disable the “Disable PHP in Plugins” option under System Tweaks.

iThemes PHP plugin setting.

​
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

html
<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>

​
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.