Troubleshooting

Quick Diagnostic Checklist

Before diving into specific issues, run through this checklist:

Extension Integration

✅ Manifest configuration is complete with all required fields
✅ CSP includes 'wasm-unsafe-eval' directive
✅ All SDK resources are listed in web_accessible_resources
✅ Content script is registered (static or dynamic)
✅ Background script initializes the SDK
✅ Extension is loaded and active in chrome://extensions
✅ No errors in service worker console

Web Integration

✅ SDK is installed in your web project
✅ Extension ID is correct for your environment
✅ Extension is installed and active
✅ HTTPS is used (if in production)
✅ Backend API endpoints are accessible (if using server config)
✅ CORS is configured correctly (if using server config)

Common Issues

Installation Issues

Asset Setup Script Fails

Symptoms: Running npm run reclaim-extension-setup produces errors

Possible Causes:

Incorrect --public-dir path
Missing public directory
File permission issues

Solutions:

# Verify public directory exists
ls -la public/
 
# Create if missing
mkdir -p public
 
# Run setup with correct path
npm run reclaim-extension-setup
 
# For custom public directory
npm run reclaim-extension-setup -- --public-dir=dist

SDK Assets Not Copied

Symptoms: Build fails because SDK files are missing

Solutions:

Verify the setup script ran successfully:

ls -la public/reclaim-browser-extension-sdk/

Check for build tool configuration issues:

// vite.config.js - ensure publicDir is set
export default {
  publicDir: 'public'
}

Manually verify file existence before build:

{
  "scripts": {
    "prebuild": "npm run reclaim-extension-setup",
    "build": "vite build"
  }
}

Manifest Configuration Issues

CSP Violations

Symptoms: Console errors like:

Refused to execute inline script because it violates CSP
Failed to load WebAssembly module

Solution: Update your CSP in manifest.json:

{
  "content_security_policy": {
    "extension_pages": "script-src 'self' 'wasm-unsafe-eval'; object-src 'self'; worker-src 'self';"
  }
}

Important: The 'wasm-unsafe-eval' directive is required for WebAssembly. Don't remove it.

Permission Denied Errors

Symptoms: Extension can't create offscreen documents or access cookies

Solution: Add required permissions to manifest.json:

{
  "permissions": [
    "offscreen",
    "cookies"
  ],
  "host_permissions": [
    "<all_urls>"
  ]
}

Resources Not Accessible

Symptoms: Console errors:

Failed to load resource: net::ERR_FILE_NOT_FOUND
denying load of chrome-extension://...

Solution: Add all SDK resources to web_accessible_resources:

{
  "web_accessible_resources": [
    {
      "resources": [
        "reclaim-browser-extension-sdk/offscreen/offscreen.html",
        "reclaim-browser-extension-sdk/offscreen/offscreen.bundle.js",
        "reclaim-browser-extension-sdk/interceptor/network-interceptor.bundle.js",
        "reclaim-browser-extension-sdk/interceptor/injection-scripts.bundle.js",
        "reclaim-browser-extension-sdk/content/components/reclaim-provider-verification-popup.css",
        "reclaim-browser-extension-sdk/content/components/reclaim-provider-verification-popup.html"
      ],
      "matches": ["<all_urls>"]
    }
  ]
}

Background Script Issues

Service Worker Not Starting

Symptoms: Background initialization doesn't run, no console logs

Debugging Steps:

Check service worker console:
- Go to chrome://extensions
- Click "service worker" link under your extension
- Look for errors
Verify syntax in background script:

# Check for syntax errors
npx eslint background.js

Add error handling:

try {
  reclaimExtensionSDK.initializeBackground();
  console.log("✅ SDK initialized");
} catch (error) {
  console.error("❌ Initialization failed:", error);
}

Service Worker Repeatedly Restarting

Symptoms: Initialization logs appear multiple times

This is normal behavior: Chrome terminates inactive service workers. Ensure you reinitialize on restart:

chrome.runtime.onStartup.addListener(() => {
  reclaimExtensionSDK.initializeBackground();
});
 
chrome.runtime.onInstalled.addListener(() => {
  reclaimExtensionSDK.initializeBackground();
});

Content Script Issues

Content Script Not Injecting

Symptoms: Verification doesn't work on web pages

Debugging:

Check if content script is loaded:

// In page console
console.log("SDK Content Script:", typeof window.__RECLAIM_SDK__ !== 'undefined');

Verify manifest registration:

{
  "content_scripts": [
    {
      "js": ["reclaim-browser-extension-sdk/content/content.bundle.js"],
      "matches": ["<all_urls>"],
      "run_at": "document_start"  // Must be document_start!
    }
  ]
}

For dynamic registration, check if registered:

chrome.scripting.getRegisteredContentScripts().then(scripts => {
  console.log("Registered scripts:", scripts);
});

Common Mistakes:

❌ Using run_at: "document_end" - won't work
❌ Missing from matches array
❌ Wrong file path in js array

Content Script Loading But Not Working

Symptoms: Script loads but verification fails

Solutions:

Ensure host_permissions includes the target domain:

{
  "host_permissions": ["<all_urls>"]
}

Check for conflicts with page scripts:

{
  "content_scripts": [
    {
      // ...
      "world": "ISOLATED"  // Recommended
    }
  ]
}

Verification Issues

Verification Never Starts

Symptoms: startVerification() called but nothing happens

Debugging:

Check console for errors in both:
- Extension popup/page
- Background service worker
- Web page (for web integration)
Verify API credentials:

console.log("APP_ID:", APP_ID);
console.log("APP_SECRET length:", APP_SECRET?.length);
console.log("Provider ID:", providerId);

Check initialization:

try {
  const request = await reclaimExtensionSDK.init(APP_ID, APP_SECRET, providerId);
  console.log("✅ Request created:", request);
} catch (error) {
  console.error("❌ Init failed:", error);
}

Verification Starts But Never Completes

Symptoms: Provider window opens but completed event never fires

Possible Causes:

User didn't complete provider authentication
Network interception failed
Offscreen document error

Debugging:

Check offscreen document console:

// In service worker console
chrome.offscreen.createDocument({
  url: 'reclaim-browser-extension-sdk/offscreen/offscreen.html',
  reasons: ['WORKERS'],
  justification: 'Debug proof generation'
}).then(() => {
  console.log("Offscreen document created");
}).catch(err => {
  console.error("Offscreen creation failed:", err);
});

Monitor all events:

const request = await reclaimExtensionSDK.init(...);
 
request.on("started", (data) => console.log("STARTED:", data));
request.on("completed", (data) => console.log("COMPLETED:", data));
request.on("error", (data) => console.error("ERROR:", data));

Check provider tab:
- Did it open correctly?
- Did user complete authentication?
- Are there errors in provider tab console?

Proofs Are Empty or Invalid

Symptoms: completed event fires but proofs are empty or malformed

Solutions:

Verify provider configuration:

// Check provider ID is valid
const validProviders = ["google-login", "twitter-profile", "github-login"];
if (!validProviders.includes(providerId)) {
  console.error("Invalid provider:", providerId);
}

Check API credentials are correct:
- Wrong credentials may produce empty proofs
- Verify on Reclaim Developer Portal
Validate proofs structure:

request.on("completed", (proofs) => {
  console.log("Proof structure:", {
    hasClaimData: !!proofs?.claimData,
    hasSignedClaim: !!proofs?.signedClaim,
    provider: proofs?.claimData?.provider
  });
});

Web Integration Issues

Extension Not Detected

Symptoms: isExtensionInstalled() returns false despite extension being installed

Solutions:

Verify extension ID:

const EXTENSION_ID = "your-extension-id-here";
console.log("Checking for extension:", EXTENSION_ID);
 
const installed = await reclaimExtensionSDK.isExtensionInstalled({
  extensionID: EXTENSION_ID
});
console.log("Installed:", installed);

Check extension ID matches:
- Development vs production IDs are different
- Get ID from chrome://extensions (enable Developer mode)
Ensure extension has proper permissions:

{
  "externally_connectable": {
    "matches": ["<all_urls>"]
  }
}

Communication Fails Between Page and Extension

Symptoms: Initialization succeeds but verification doesn't start

Debugging:

Check content script is loaded on the page:

// In page console
window.addEventListener('message', (event) => {
  console.log('Message received:', event.data);
});

Verify CORS for server config:

// Backend
app.use(cors({
  origin: process.env.ALLOWED_ORIGINS.split(','),
  credentials: true
}));

Check for CSP blocking communication:

<!-- In your web page -->
<meta http-equiv="Content-Security-Policy"
      content="default-src 'self'; connect-src 'self' chrome-extension://*">

Build Tool Issues

Vite Re-bundling SDK Assets

Symptoms: Build errors related to SDK bundles

Solution: Ensure assets are in public directory and not imported:

// ❌ Don't do this
import contentScript from '@reclaimprotocol/browser-extension-sdk/content/content.bundle.js';
 
// ✅ Reference from public directory via manifest
{
  "content_scripts": [
    {
      "js": ["reclaim-browser-extension-sdk/content/content.bundle.js"]
    }
  ]
}

Create React App (CRA) Issues

Symptoms: Build fails or SDK doesn't work after build

Solutions:

Verify public folder structure:

public/
├── reclaim-browser-extension-sdk/
│   ├── content/
│   ├── offscreen/
│   └── interceptor/
└── manifest.json

Use correct paths in manifest:

{
  "content_scripts": [
    {
      "js": ["reclaim-browser-extension-sdk/content/content.bundle.js"]
      // NOT: "public/reclaim-browser-extension-sdk/..."
    }
  ]
}

Environment Variable Issues

Variables Not Loading

Symptoms: undefined values for environment variables

Solutions:

Check variable prefix:

// Vite
import.meta.env.VITE_RECLAIM_APP_ID  // ✅
process.env.VITE_RECLAIM_APP_ID      // ❌
 
// CRA
process.env.REACT_APP_RECLAIM_APP_ID // ✅
import.meta.env.REACT_APP_...        // ❌

Restart dev server after changing .env:

# Stop server (Ctrl+C)
npm run dev

Verify .env file location:

# Should be in project root
ls -la .env.local

Debugging Tools

Enable Debug Mode

Create a debug utility:

const DEBUG = import.meta.env.MODE === 'development';
 
export const debug = {
  log: (...args) => DEBUG && console.log('[DEBUG]', ...args),
  error: (...args) => DEBUG && console.error('[ERROR]', ...args),
  warn: (...args) => DEBUG && console.warn('[WARN]', ...args)
};
 
// Usage
debug.log('Initializing SDK with', { APP_ID, providerId });

Log All SDK Events

const request = await reclaimExtensionSDK.init(...);
 
['started', 'completed', 'error'].forEach(eventName => {
  request.on(eventName, (data) => {
    console.log(`[${eventName.toUpperCase()}]`, {
      timestamp: new Date().toISOString(),
      data
    });
  });
});

Check Extension State

// In extension background
chrome.management.getSelf((info) => {
  console.log('Extension info:', {
    enabled: info.enabled,
    version: info.version,
    permissions: info.permissions
  });
});

Performance Issues

Slow Proof Generation

Symptoms: Verification takes a long time

Possible Causes:

WebAssembly not loading properly
Offscreen document not created
Network issues

Solutions:

Verify WASM loading:

// Check CSP allows WASM
console.log(document.querySelector('meta[http-equiv="Content-Security-Policy"]'));

Monitor offscreen document:

// Log offscreen creation
chrome.offscreen.createDocument(...).then(() => {
  console.log('⏱️ Offscreen created at', Date.now());
});

Extension Slowing Down Browser

Symptoms: Browser becomes sluggish

Solution: Check for memory leaks:

// Cleanup after verification
request.on("completed", (proofs) => {
  // Process proofs
  handleProofs(proofs);
 
  // Clear references
  request = null;
});
 
request.on("error", (error) => {
  // Handle error
  handleError(error);
 
  // Clear references
  request = null;
});

Getting Help

If you've tried everything and still have issues:

Check Console Logs:
- Extension popup console
- Background service worker console
- Web page console (for web integration)
- Provider tab console
Gather Information:
- Extension version
- Browser version
- SDK version
- Error messages
- Steps to reproduce
Test in Isolation:
- Create a minimal reproduction
- Test with basic credentials
- Try different providers
Community Support:
- GitHub Issues
- Discord Community (if available)
- Documentation

Prevention Checklist

Before deploying:

✅ Tested in both development and production builds
✅ Verified all environment variables are set
✅ Tested extension installation flow
✅ Implemented proper error handling
✅ Added user-friendly error messages
✅ Tested with multiple providers
✅ Verified proof validation on backend
✅ Tested edge cases (cancellation, timeout, etc.)
✅ Checked for memory leaks
✅ Reviewed console for warnings

Troubleshooting

On this page