If you haven't tried our Video Setup guides, see our WordPress Setup or Typical Setup if you need setup help.

OneSignal prints helpful error messages in your browser's Developer Tools Console when viewing your site with the OneSignal code active. Follow these steps to open the Chrome Developer Tools Console and check for errors on the site:

1. Click the "lock icon" next to your URL in the Chrome browser.
2. Next to "Notifications" permission dropdown, select "Ask (default)" (if you do not see this skip to step 3).
3. Click Cookies to open the browser's "Cookies in use" page.
4. Find and select your site (if you do not see your site, skip to step 8).
5. Click Remove.
6. Click Done.
7. You should see a dropdown prompt to "Reload the page". Click the Reload button.

If you have immediate Prompting setup, you should now see a prompt on your site. Do not attempt to subscribe to your site yet.

8. Right click on your site's page and select "Inspect".
9. Select the "Console" tab.

10. Now Subscribe to your site by going through the prompting steps. See the Prompting Guide if you have not setup your prompts yet.
11. After you click "Allow" on the Native Browser Prompt you may see one or more of the following errors:

403 or 404 Service Worker Installation Errors - There is a common error thrown when trying to connect with the OneSignal Service Worker files. More details on how to fix this see: 403 or 404 Service Worker Installation Errors.

Web Push Config can only be used on "correct site origin" - Your current site origin does not match your settings in the OneSignal Dashboard. See Incorrect Site Url Error.

OneSignal is already defined. The OneSignal web SDK can only be initialized once. - You add the OneSignal init code twice, usually if you have our WordPress plugin and added code directly. See OneSignal Initialized Twice.

403 & 404 Service Worker Errors

After you try subscribing to your site, if you see a 403 or 404 error in your Browser Console and/or in your onesignal.com Dashboard > Audience > All Users page, that means something is blocking the OneSignal Service Worker files from being publicly accessible.

These files must be spelled with the upper case letters and not redirects.
You should be able to visit these pages without any errors and see just a white screen with 1 line of code.

Typical Setup, Custom Code Setup (sites that do not use the OneSignal Plugin) should be able to view them at:

• https://yoursite.com/OneSignalSDKWorker.js
• https://yoursite.com/OneSignalSDKUpdaterWorker.js

WordPress Setup users with our OneSignal WordPress Plugin should be able to view them at:

• https://yoursite.com/wp-content/plugins/onesignal-free-web-push-notifications/sdk_files/OneSignalSDKWorker.js.php
• https://yoursite.com/wp-content/plugins/onesignal-free-web-push-notifications/sdk_files/OneSignalSDKUpdaterWorker.js.php

Common reasons for these being being inaccessible:

Incorrect Configuration

Login to onesignal.com and select Your App > Settings > All Browsers Configuration.

1. If you are not using our WordPress Plugin, select 1 or 3 (Typical Setup or Custom Code Setup).
2. If you are using our WordPress Plugin make sure you selected 2 WordPress Plugin or Website Builder

CDN Issues or Redirects

Make sure OneSignalSDKWorker.js and OneSignalSDKUpdaterWorker.js are being served from the same top-level domain of your site. It cannot be served by a CDN or a redirect or a domain other than the domain the visitor is currently on. See the Same Origin Policy Guide for more details on this browser restriction.

WordPress Plugin Users see common CDN and Cacheing Plugins to fix this.

Non-WordPress users see our OneSignal Service Worker FAQ if you cannot add the files to the root directory.

PWA or Multiple Service Workes

If you are integrating OneSignal into a site with an existing service worker (like a PWA), you may have to merge service workers in order for OneSignal to work correctly. See OneSignal Service Worker FAQ for more details.

How do I check if my OneSignal service-worker is configured correctly?

In your browser's development tools, go to the Service Workers section (under "Application" tab in Chrome) and look for "OneSignalSDKWorker.js" as the source for the service-worker for your domain. Detailed Steps to Reproduce.

If you do not see the OneSignal service worker there, you have not configured OneSignal correctly.

If you only see a different service-worker on your site, it may be causing a conflict with OneSignal's service-worker. Try merging the service-workers to resolve the issue.

Incorrect Site URL

Make sure your site url is correct.

• www and non-www are different. Set site url in OneSignal based on the version you want to use.
• HTTP and HTTPS are also very different. More details in Web Push HTTP vs. HTTPS
• Ignore Subdirectories having a subdirectory like /blog does not affect this and can be ignored for setup purposes.

HTTP sites must add a Label that is 4 letters or more.

WordPress users with HTTP sites, make sure your Label matches the plugin OneSignal Label. Do not add os.tc to the OneSignal Label field. Press "Save" at the bottom of the plugin if you updated this.

Wrong Browser, Viewing Mode, or Browser Version

1. Make sure you are testing with the latest version of Chrome or Firefox.
2. Do not use incognito mode, private browser mode or guest browser mode or Firefox's ESR versions. Subscription to push does not work in these modes.
3. Apple currently still does not support Web Push Notifications on iOS mobile devices like iPhones and iPads. Currently iPhones and iPads can only get notifications from mobile apps, not from websites.
4. Supported browsers can be viewed in the Web Push Overview.

My site isn't working on my mobile phone

iOS - Apple currently still does not support Web Push Notifications on iOS mobile devices like iPhones and iPads. For more information, please read our Blog Post.

Android - Web push works automatically on android mobile devices using a supported browser.

1 - First make sure your site works on Desktop before testing on mobile

2 - You may be subscribed on android web already, but our dashboard does not differentiate mobile web subscribers from desktop web subscribers.

An android web subscriber shows as "Linux armv8l" in the Device column of the "All Users" page.

3 - Check if Notifications are enabled on Chrome in your Android Settings > Application Manager > Chrome. Make sure "Show notifications" is checked like this: https://i.imgur.com/LY810Mj.png on Firefox it will be the same: https://i.imgur.com/a3lB88b.png

4 - Clear your Chrome Cache. If your browser cache is full on mobile, this may not allow further prompting or subscription. Follow Clearing your cache and resetting push permissions based on your browser to test your site again.

Safari Troubleshooting

1 - Apple currently still does not support Web Push Notifications on iOS mobile devices like iPhones and iPads. For more information, please read our Blog Post.

2 - The icon you uploaded on the OneSignal Dashboard > App Settings > Safari Configuration MUST to be exactly 256X256.

3 - The Site URL set in the Safari Config must be exactly what you see when visiting the site. For example, if you see https://www.yoursite.com in the browser, then you must add this to the setup field. www and non-www sites are different origins.

4 - Safari 12.1 created a new rule that users must perform some action on the site before they can get prompted

This is why the slide prompt always shows before native if you use our Typical Setup

If you want to use only the native browser prompt, you will need to setup your own trigger to detect a user action. Then call OneSignal.showNativePrompt(); when you want to show the native prompt. Otherwise, please use the OneSignal.showSlidedownPrompt(); if you are having issues.

5 - Finally, try clearing your browser data to see your site as a first time user and try to subscribe again.

Safari Icons Or Site Name Not Changing

Due to Safari's custom web push implementation, your site name and icon image are treated as static resources downloaded and stored locally on the user's computer. New site names and new images are not updated or downloaded.

Unfortunately anyone subscribed with these older resources will need to clear the Safari push permissions and return to the site to resubscribe.

Clearing your cache and resetting push permissions

Even if your settings are configured correctly, if you had previously used incorrect settings, push notifications may not work due to invalid permission or background worker states. These steps will reset your site's notification permissions, clear your site's storage, and remove our background worker.

Chrome (Desktop)

1. Click the icon next your site. Make sure Notifications says Use global default (Ask). If you don't see this -- move on to the next step.

2. Clear site data - On this same panel click "Show cookies and site data" (Windows) or "# in use" (Mac).

Select all the entries at once and click "Remove". No entries should be left.

3. If you have selected My Site is not Fully HTTPS in the Web Push Editor or are using a Website Builder that requires you add a label, visit yourlabel.os.tc and repeat steps 1 - 2 for this URL.

4. Close tabs and windows pointing to your domain or yourlabel.os.tc. This is actually an important step -- don't skip it!

5. Visit chrome://serviceworker-internals/ in a new tab and press the 'Stop' and 'Unregister' buttons under any Scopes that contain yoursite.domain or yourlabel.os.tc. If they won't remove, make sure all tabs or windows pointing to either domain are closed.

Chrome (Android)

If you still have a notification from your site visible in your notification drawer:

1. Click the gear icon and 'Site Settings'.

   
   

   

2. Click 'Clear & Reset'.

   
   

   

If you do not have a notification open, open Chrome on Android, tap the 3-dot menu, Settings, Site settings (under Advanced), Notifications, make sure it's set to "Ask before sending (recommended)". Find your site on the list, click the entry, and click Clear and Reset.

Firefox (Desktop)

1. Click the "i" or "lock" icon next to your site URL.
2. Next to Receive Notifications under Permissions select the "X" button next to Allowed

3. On the same dialog, at the bottom select Clear Cookies and Site Data...

4. On the popup dialog that opens, click "OK"

Firefox (Android)

Please follow this Firefox guide to clear all your browser data.

Safari (Mac OS X Desktop)

On the top menu bar, go to Safari -> Preferences -> Websites -> Notifications and remove your site's entry. Then in the same preferences dialog, go to the Privacy tab and click Clear Website Data.

On the top menu bar, go to Safari -> Preferences -> Websites -> Notifications and remove your site's entry.
Under Websites -> Pop-up Windows if present, make sure your site shows Allow if present.
Then in the same preferences dialog, go to the Privacy tab and click Clear Website Data.

Debugging using Browser Developer Tools

The browser's developer tools can be used to interact with the web SDK on your webpage and enable logging or easily send test notifications to yourself.

1. Access the Browser Developer Tools Console

Chrome - Right click on the page, click Inspect, and click the Console tab of the popup window that opens up.

Firefox - Right click on the page, click Inspect element, and click the Console tab of the popup window that opens up.

Safari - Go to Safari -> Preferences -> Advanced and make sure Show Develop menu in menu bar is checked. Then, on your webpage, right click, click Inspect element, and click the Console tab of the popup window that opens up.

Chrome on Android - Debugging on Chrome on Android is more complicated, and requires a USB cable to connect your Android phone to your computer. Please follow this guide to remotely access your mobile Chrome's Developer Tools console.

Firefox on Android - Debugging on Firefox on Android is more complicated, and requires a USB cable to connect your Android phone to your computer. Please follow this guide to remotely access your mobile Firefox's Developer Tools console.

2. Enable web SDK logging

You should be able to run commands in the developer tools Console now.

Execute the following code:

OneSignal.log.setLevel('trace');

You should see undefined as the result.

If you see:

Uncaught ReferenceError: OneSignal is not defined(…) or ReferenceError: OneSignal is not defined, then OneSignal is not active on your webpage, or you need to switch to the top frame context (see above screenshot at the beginning of this section).

Now that our web SDK's debug logging is enabled, please close the tab and open a new tab to the same page (refreshing the page is not enough to trigger some of our SDK events). You should see a lot of output in the Console.

You can always disable this additional logging by entering this code:

OneSignal.log.setLevel('warn');

3. Check if you are subscribed

Run in the Console:

function isPushNotificationsEnabledVerbose() {
    console.log('isPushNotificationsEnabledVerbose()');
    Promise.all([
            OneSignal.isPushNotificationsEnabled(),
            OneSignal.getUserId(),
            OneSignal.getRegistrationId(),
            OneSignal.getNotificationPermission(),
            OneSignal.isOptedOut(),
            OneSignal.context.serviceWorkerManager.getActiveState()
        ])
        .then(([isSubscribed, userId, registrationId, notificationPermission, optedOut, serviceWorkerActive]) => {
            console.log('Is Completely Subscribed:', isSubscribed);
            console.log('');
            console.log('What is our OneSignal user ID?', userId);
            console.log('What is our push subscription token?', registrationId);
            console.log('What is the notification permission status?', notificationPermission);
            console.log('Are you manually opted out?', optedOut);
            console.log("Is a service worker registered and active? (should be false on Safari, otherwise should be 'Worker A (Main)')?", serviceWorkerActive);
            console.log('What is the current URL of this page?', location.href);
            console.log("What environment does OneSignal think it's in?", OneSignal.sdkEnvironment.getWindowEnv());
        })
        .catch(e => {
            console.error("Issue determining whether push is enabled:", e);
        });
}
isPushNotificationsEnabledVerbose();

Depending on whether you are subscribed, you should see:

Is Completely Subscribed: true

What is our OneSignal user ID? b7b14773-e053-44b6-8eee-1a8fe58c53ba
What is our push subscription token? fwJQA8TYCTk:APA91bFbQyYR9kVvgmxHGV7fKr7sktzh4v2fEXad2KRlqq_zupfUexqbPscpcQ4Iru3IAOQ9sIrrt1TtlUySK1Jy2Vg7lzwpGHCRLBqa-er2cuQ6T79AG9l4MWKrwTfehWcBTDj_BdGD
What is the notification permission status? granted
Are you manually opted out? false
Is a service worker registered and active? true
What is the current URL of this page? https://example.com
What environment does OneSignal think it's in? host

4. Send yourself a test notification

Only if you are subscribed (see above section), you can send yourself a test notification. This notification will only go to you and your other users will not receive this notification. In the console, run:

OneSignal.sendSelfNotification()

You should see something similar to Promise {[[PromiseStatus]]: "pending", [[PromiseValue]]: undefined}, and you should receive a web push notification shortly after. Make sure you aren't using Private Browsing Mode / Incognito mode on Chrome or Chrome's full screen mode as this can hide and disable notifications.

Debugging not receiving Chrome notifications

Note: Please complete these steps in order.

1. Please see My site isn't working in Chrome. You can't receive notifications in full screen mode, for example.

2. Please follow steps 1 - 4 in the section Debugging using Browser Developer Tools to try receiving a test notification.

   • For step #3, are you subscribed? If not, stop here, completely clear your site data following these specific instructions, and then re-subscribe to your site in order to receive notifications. Run step #3 again after to verify you're actually subscribed. When following the clear site data instructions, please do remember to close all tabs to your site or restart your browser, since Chrome prevents the site's storage from being accessed until all existing tabs to your site are closed.

   • For step #4, do you receive a test notification? If you do, you're done!

3. If you're subscribed but you did not receive a test notification, please visit your OneSignal dashboard, visit the Sent Messages page, and click "Viewing: API Notifications" to view the test notifications you've sent yourself. Are they colored red (Invalid)? If they are colored red and Invalid, your web push keys are most likely mismatched. Please let us know on support about this.

4. If you're subscribed, did not receive a test notification, but you see the message has been delivered (colored green), please open Chrome to chrome://gcm-internals. Click the "Start Recording" button on the top left. Follow step #4 above to send yourself a test notification. Do you see a "Data msg received" like in the below screenshot (make sure to click "Start Recording" first)?

   • If you don't see a "Data msg received", then your Chrome browser is not receiving the notification at all. Please let us know on support about this.

   • If you see "Data msg received" but you still didn't receive a notification, proceed to step #5.

5. Visit chrome://serviceworker-internals.

   If your site is an HTTPS site like https://example.com, search for Scope: https://example.com.

   If you selected My Site is Not Fully HTTPS and chose a label for your site, search for Scope: https://mylabel.os.tc where mylabel is the label you chose for your site.

   Click Inspect, or Start -> Inspect, like below. A Chrome Developer Tools popup will appear.

6. On the Chrome Developer Tools popup to our service worker, click the Console tab, and run OneSignalWorker.log.setLevel('trace');. It should return undefined. Any messages from our service worker should now appear in this pop

7. Switch away from the worker's Dev Tools popup, and back to your main page's Developer Tools console (where you followed step 2). Please send yourself another test notification. You should a lot of output here with an error since you did not see the notification. Please on support about this error. You can right click on the Console -> Save as ... and copy the file contents to our chat support.