Troubleshooting

Troubleshooting

SW not registering

In DevTools Application -> Service Workers, look for the error. Common causes:

• Site not on HTTPS
• A Content-Security-Policy header blocking inline workers
• Another plugin returning HTML at /sw.js. Hit /sw.js directly in the browser; the response must be JavaScript with Content-Type: application/javascript

If the URL 404s, flush WordPress rewrites (Settings -> Permalinks -> Save).

Push payload arrives but contains nothing

Almost always a VAPID key mismatch. Regenerate keys in Push Notifications -> VAPID -> Generate and unsubscribe/resubscribe a test browser.

"WebPush" errors in the PHP log

On PHP < 8.1, oPWA needs the gmp extension for ECDH. Either upgrade PHP or apt-get install php-gmp (or your distro's equivalent).

Manifest not showing in DevTools

Hit /manifest.webmanifest directly. The response must be JSON with Content-Type: application/manifest+json. If you see a 404, the rewrite rule didn't register; flushing permalinks fixes it.

Offline page shows the default browser error

Set an offline fallback in oPWA -> Offline and confirm that page is in the precache list. Without precache, the SW has nothing to serve.