Chrome Extension Debugging Checklist — Developer Guide

5 min read

Extension Debugging Checklist

This checklist provides a systematic approach to diagnosing and fixing common Chrome extension issues. Each section covers a specific problem area with symptoms, likely causes, diagnostic steps, and fixes.

Table of Contents

Manifest Issues

Symptom: Extension fails to load or shows errors in chrome://extensions

Likely Causes:

How to Diagnose:

  1. Open chrome://extensions and look for error messages under your extension
  2. Validate manifest.json using Chrome Extension Manifest Validator
  3. Check for trailing commas or malformed JSON

How to Fix:

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0",
  "permissions": ["storage", "tabs"],
  "host_permissions": ["<all_urls>"]
}

Service Worker Issues

Symptom: Service worker not registering or not responding to events

Likely Causes:

How to Diagnose:

  1. Open chrome://extensions, click “Inspect views: service worker”
  2. Check chrome://serviceworker-internals for registration status
  3. Look for console errors on SW startup

How to Fix:

// Persist state to survive restarts chrome.storage.local.set({ key: value });


### Symptom: Lost state after service worker restarts {#symptom-lost-state-after-service-worker-restarts}

**Likely Causes:**
- Storing state in global variables
- Service worker lifecycle terminates and resets memory

**How to Diagnose:**
1. Add console.log at SW startup to detect restarts
2. Check chrome.storage for persisted state

**How to Fix:**
- Use `chrome.storage.session` for temporary state
- Use `chrome.storage.local` for persistent state
- Re-initialize state on each SW startup

---

## Content Script Issues {#content-script-issues}

### Symptom: Content script not injecting or not running {#symptom-content-script-not-injecting-or-not-running}

**Likely Causes:**
- Incorrect match patterns in manifest
- Wrong `run_at` timing
- Page conditions not met (SPA navigation, dynamic content)

**How to Diagnose:**
1. Open DevTools on the target page, check "Content scripts" in Sources panel
2. Verify match patterns match the current URL
3. Check if script is declared under `content_scripts` in manifest

**How to Fix:**
```json
{
  "content_scripts": [{
    "matches": ["<all_urls>"],
    "js": ["content.js"],
    "run_at": "document_idle"
  }]
}

Symptom: CSS conflicts with page styles

Likely Causes:

How to Diagnose:

  1. Inspect elements in DevTools to see applied styles
  2. Check for extension styles bleeding into page

How to Fix:

Messaging Issues

Symptom: Messages not delivered or no response

Likely Causes:

How to Diagnose:

  1. Add console.log in both sender and receiver
  2. Check “Could not establish connection” errors in console
  3. Verify sender and receiver contexts are active

How to Fix:

// Content script - sender
chrome.runtime.sendMessage({ type: 'GET_DATA' });

// Service worker - receiver with async response
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === 'GET_DATA') {
    asyncOperation().then(result => sendResponse(result));
    return true; // Keep channel open for async response
  }
});

Symptom: “The message port closed before a response was received”

Likely Causes:

How to Fix:

Storage Issues

Symptom: Storage quota exceeded errors

Likely Causes:

How to Diagnose:

  1. Check chrome.storage.local.getBytesInUse()
  2. Compare against quota constants like chrome.storage.local.QUOTA_BYTES

How to Fix:

Symptom: sync vs local confusion

Likely Causes:

How to Diagnose:

  1. Check if data appears in chrome://settings
  2. Verify storage type matches use case

How to Fix:

UI Issues

Symptom: Popup not showing or showing blank

Likely Causes:

How to Diagnose:

  1. Right-click extension icon -> “Inspect popup”
  2. Check Console for errors
  3. Verify popup path in manifest

How to Fix:

{
  "action": {
    "default_popup": "popup.html",
    "default_icon": "icon.png"
  }
}

Symptom: CSP blocking extension functionality

Likely Causes:

How to Fix:

Cross-references

Part of the Chrome Extension Guide by theluckystrike. Built at zovo.one.

← Previous extension-bundle-analysis Next → extension-error-reporting