Fix Chrome Service Worker Inactivity Timeout Bugs (30-Sec)

Is your Chrome extension failing to finish long-running tasks? You might notice that file uploads stall midway, periodic health checks stop firing, or websockets disconnect unexpectedly. This is the single most common headache developers encounter in Manifest V3.

Chrome enforces a strict 30-second inactivity rule on background service workers. If your extension does not receive a message or trigger an event for 30 seconds, the browser puts it to sleep to conserve memory and battery life.

Executive Summary

  • The 30-Second Rule: Chrome terminates background service workers after 30 seconds of inactivity, breaking long-running timers and websockets.
  • Why setInterval Fails: Standard window timers like setInterval and setTimeout are paused or cancelled when the service worker goes to sleep.
  • Solution 1: chrome.alarms: Use the Chrome Alarms API to schedule recurring background tasks that wake up your worker reliably.
  • Solution 2: Offscreen Documents: For continuous streams, audio playback, or persistent connections, offload work to a dedicated offscreen document.

Table of Contents

Long-Running Task Solutions in Chrome Manifest V3

Task TypeLegacy V2 ApproachBroken V3 ApproachThe Working Manifest V3 Solution
Periodic PollingsetInterval() loopsetInterval() inside worker (sleeps)chrome.alarms API with periodic wake-ups.
WebSocket ConnectionsPermanent socket in backgroundSocket drops when worker idleReopen socket on demand or use offscreen doc.
Long File UploadsSingle long-running fetch loopTerminates if upload stalls >30sChunked uploads with progress storage sync.
Audio NotificationsHTML5 No DOM access in service workerchrome.offscreen API playing audio in background.

Understanding the Service Worker Termination Headache

Is your Chrome extension failing to finish long-running tasks? You might notice that file uploads stall midway, periodic health checks stop firing, or websockets disconnect unexpectedly. This is the single most common headache developers encounter in Manifest V3.

Chrome enforces a strict 30-second inactivity rule on background service workers. If your extension does not receive a message or trigger an event for 30 seconds, the browser puts it to sleep to conserve memory and battery life.

Trying to fight this behavior with hacks like infinite `setInterval` loops does not work. Chrome detects idle loops and forcibly terminates the process anyway. Fortunately, there are three clean, platform-supported ways to resolve this.

Solution 1: Use chrome.alarms Instead of setInterval

If your extension needs to check an API every few minutes or perform periodic cleanups, never use JavaScript’s `setInterval`. When your service worker shuts down, the timer stops completely.

Instead, use the Chrome Alarms API. Alarms operate at the browser level, meaning Chrome will wake your service worker up specifically when the alarm triggers.

Add `’alarms’` to your `manifest.json` permissions. Create an alarm using `chrome.alarms.create(‘checkApi’, { periodInMinutes: 5 })` and listen for it using `chrome.alarms.onAlarm.addListener()`. Your task will run reliably on schedule.

Solution 2: Maintain Active Connections with Runtime Ports

If your service worker is communicating with an active popup or side panel, standard one-off `chrome.runtime.sendMessage` calls might not keep the worker awake during complex operations.

Instead, establish a persistent connection using `chrome.runtime.connect()`. A long-lived Port connection tells Chrome that active communication is underway, extending the service worker lifetime while the port remains open.

Once the user closes the popup or the task finishes, disconnect the port to let the worker sleep naturally. This ensures maximum battery efficiency while preventing premature shutdowns.

Solution 3: Offload Continuous Work to Offscreen Documents

What if your extension genuinely needs continuous execution, such as recording user audio, streaming websockets, or parsing large DOM documents? Service workers are not designed for continuous tasks.

The official Chromium solution is the Offscreen Documents API. You can spawn an invisible HTML document using `chrome.offscreen.createDocument({ reasons: [‘AUDIO_PLAYBACK’], justification: ‘Play sound’ })`.

Because offscreen documents have full DOM access and are not subject to the 30-second timeout, they can run continuous streams safely. Once the task finishes, close the offscreen document to release resources.

Frequently Asked Questions

What is the minimum interval for chrome.alarms in production?

In release builds, Chrome limits alarms to a minimum frequency of once every 1 minute to prevent battery drain. In unpacked developer mode, alarms can fire every few seconds.

Can a WebSocket keep my service worker alive forever?

No. Chrome will terminate a service worker with an open WebSocket if no active messages are sent or received for 30 seconds. To maintain continuous sockets, use an offscreen document.

Does closing an offscreen document stop its running scripts?

Yes. Calling chrome.offscreen.closeDocument() completely unloads the document and frees all associated memory and network connections.

We hope this tutorial helped you level up your browser engineering. Explore related guides from our topic cluster:

Primary Sources & References

Written by the TeckScaler Editorial Engineering Team. We provide practical, beginner-friendly tutorials, architectural blueprints, and modern browser customization guides.