Skip to main content

​
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
  1. 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.
OneSignal WordPress plugin settings showing Custom Post Types field

​
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.
Browser DevTools open with the Console tab selected on a WordPress site
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.
Browser console showing OneSignal User PushSubscription id string result
4

Verify Subscription ID in OneSignal dashboard

In the OneSignal dashboard, go to Audience > Subscriptions and search for the ID returned above.
OneSignal dashboard Subscriptions search field with subscription ID lookup
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 …

Console SdkInitError showing web push config origin mismatch
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.

Console error OneSignal web SDK can only be initialized once
You’re loading OneSignal twice. Remove manually added OneSignal code if you’re using the plugin.

​
Installing service worker failed.. 403 or 404 error

Console error installing service worker failed with 403 or 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:
PlaceholderReplace with
YOURSITEHEREYour bare domain (regex segment), e.g. example for example.com
mywpenginehandleHereYour WP Engine install name (subdomain before .wpengine.com)
wpengineCDNpathHereYour NetDNA / CDN path segment from WP Engine (often shown in CDN URLs)
mywebsiteHereYour 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 CDN rejected files list including OneSignal sdk_files path

​
BunnyCDN

Exclude onesignal in the plugin’s CDN Excluded Paths.
BunnyCDN WordPress plugin excluded paths including onesignal

​
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 CDN exclude content field with OneSignal sdk_files path

​
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 list showing script exclusions

​
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.
Security plugin setting to allow PHP in plugins unchecked or disabled

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