Resolving Browser Cache and Service Worker Issues

Server Scout's dashboard is built as a Progressive Web App (PWA) that uses service workers to cache static assets for lightning-fast loading and offline access. Whilst this provides an excellent user experience, it can occasionally lead to cache-related issues that prevent you from seeing the latest updates or cause unexpected behaviour.

Common Symptoms

You might be experiencing cache or service worker issues if you notice:

• The dashboard displays an outdated user interface after a Server Scout update
• JavaScript errors appearing in the browser console
• New features or menu items that should be available aren't visible
• The dashboard behaves inconsistently or appears to "flicker" between old and new versions
• Error messages about failed resource loading

Quick Fix: Hard Refresh

The fastest solution is to perform a hard refresh, which bypasses the cache and forces your browser to fetch fresh resources:

Windows/Linux: Press Ctrl+Shift+R macOS: Press Cmd+Shift+R

This should resolve most cache-related issues immediately. If the problem persists, you'll need to manually clear the service worker and cached data.

Clearing the Service Worker

If a hard refresh doesn't resolve the issue, you'll need to manually unregister the service worker:

1. Open your browser's Developer Tools (F12 or right-click → Inspect)
2. Navigate to the Application tab (Chrome/Edge) or Application panel (Firefox)
3. In the left sidebar, click on Service Workers
4. Find the Server Scout service worker in the list
5. Click Unregister next to the service worker entry
6. Refresh the page normally (F5 or Ctrl+R)

Clearing Site Data

For persistent issues, you may need to clear all cached site data:

1. With Developer Tools open, go to the Application tab
2. In the left sidebar, locate the Storage section
3. Click on Storage to expand the options
4. Click Clear site data or Clear storage
5. Ensure all checkboxes are selected (Local storage, Session storage, Cache storage, etc.)
6. Click Clear site data
7. Close and reopen your browser tab

Why This Happens

Server Scout's service worker employs a cache-first strategy for static assets like CSS, JavaScript, and images. This means your browser checks its local cache before requesting files from the server, dramatically improving load times and enabling offline functionality.

When we deploy updates to Server Scout, the service worker's CACHE_NAME version is incremented to ensure new assets are cached properly. However, there's a brief window during deployment where users might encounter stale content:

1. During deployment: New assets are deployed but your browser still has the old service worker
2. Cache mismatch: The old service worker tries to serve cached assets that may no longer be compatible
3. Activation delay: The new service worker typically activates on your next visit, but this isn't always immediate

This timing issue can cause users who visit during the deployment window to experience inconsistent behaviour until their cache is properly updated.

Important Note About Data

It's worth noting that whilst the user interface assets use cache-first strategy, all API calls to retrieve your server monitoring data use a network-first approach. This means your actual monitoring data—server metrics, alerts, and statistics—are always fresh and up-to-date, even when experiencing UI cache issues.

The caching strategy only affects the dashboard's appearance and functionality, never your underlying server data.

Prevention

Modern browsers typically handle service worker updates automatically, and these issues are relatively rare. However, if you frequently encounter cache problems, consider:

• Enabling automatic browser updates to ensure you have the latest caching improvements
• Bookmarking the hard refresh keyboard shortcut for quick troubleshooting
• Clearing your browser cache regularly as part of routine maintenance

Following these steps should resolve any cache-related issues and restore full functionality to your Server Scout dashboard.