20. Troubleshooting

Service worker not registering

• Verify the site is served over HTTPS (or localhost).
• Check browser DevTools → Application → Service Workers for errors.
• Ensure no other plugin intercepts requests to /sw.js. The SW is served at init priority 1 via WordPress, not as a real file.
• If using a CDN, ensure /sw.js and /manifest.webmanifest are excluded from the CDN cache.

Push notifications not received

1. Confirm VAPID keys are generated (Settings → VAPID Wizard step 1 shows a public key).
2. Check subscriber table is not empty — users must visit the site and accept the permission prompt.
3. Test with Send Test Push button.
4. Check browser DevTools → Application → Push Messaging for errors.
5. HTTP 410 from the push service means the subscription is expired — the plugin deletes it automatically.
6. Firefox requires --allow-feature=web-push in some testing environments.

Icons not generating

• Verify the PHP GD extension is active: php -m | grep gd
• The source attachment must be at least 512×512 pixels.
• The wp-content/uploads/opwa-icons/ directory must be writable.

ECDH / encryption errors

• PHP < 8.1 requires the GMP extension for the P-256 fallback: php -m | grep gmp
• PHP 8.1+ uses openssl_pkey_derive() natively.
• OpenSSL must be compiled with EC curve support (openssl ecparam -list_curves | grep prime256v1).

Manifest not linking

• Check that another plugin is not outputting a <link rel="manifest"> pointing elsewhere.
• The plugin hooks into wp_head to output the manifest link. If your theme removes wp_head, re-add it.

Background sync not firing

• Background Sync is only supported in Chromium browsers.
• Verify background_sync is enabled in the Service Worker settings tab.
• Check the SW DevTools → Background Sync for queued tags.

WooCommerce checkout issues

• Enable WooCommerce Mode in Settings to force network-only on /checkout, /cart, /my-account.
• If using a custom WooCommerce checkout URL, add a network-only custom route for it.

Documentation generated for oPWA v1.0.0 — Orravo