Troubleshooting

This guide covers common issues and their solutions for the PRIV Chrome extension.

Extension Not Loading

Symptoms

• Extension icon doesn't appear in toolbar
• Extension shows as "Error" in chrome://extensions
• Popup doesn't open when clicking icon

Solutions

Check Chrome Version

The extension requires Chrome 110 or higher.

1. Open Chrome
2. Go to chrome://settings/help
3. Check your version
4. Update if below 110

Reinstall the Extension

1. Go to chrome://extensions
2. Remove the PRIV extension
3. Restart Chrome
4. Reinstall the extension

Check Developer Mode (Manual Install)

For manually installed extensions:

1. Go to chrome://extensions
2. Ensure Developer mode is enabled
3. Click Load unpacked again
4. Select the dist folder

Check for Errors

1. Go to chrome://extensions
2. Find PRIV Protocol
3. Click Errors if shown
4. Review error messages

Common errors:

Wallet Connection Issues

Cannot Connect Wallet

MetaMask Not Detected

Symptom: "No wallet found" message

Solutions:

1. Ensure MetaMask is installed
2. Refresh the extension popup
3. Restart Chrome

# Check if MetaMask is injecting properly
# Open DevTools console on any page
typeof window.ethereum  // Should not be 'undefined'

Connection Rejected

Symptom: Connection request disappears or fails

Solutions:

1. Look for MetaMask popup (might be minimized)
2. Click the MetaMask icon in toolbar
3. Approve the pending connection
4. If stuck, lock/unlock MetaMask

Wrong Account Connected

Symptom: Different address than expected

Solutions:

1. Open MetaMask
2. Switch to correct account
3. Extension will detect the change
4. Verify address in extension header

Wallet Keeps Disconnecting

Symptom: Wallet disconnects frequently

Solutions:

1. Check if MetaMask is locked
2. Don't close MetaMask popup before approving
3. Update MetaMask to latest version
4. Clear extension data and reconnect

// Manually clear wallet data
chrome.storage.local.remove(['priv_wallet_address']);

Data Not Syncing

No Data Points Showing

Symptom: Data points stay at 0

Solutions:

Check Data Sharing Status

1. Open extension
2. Verify Data Sharing is enabled
3. Enable at least one data type

Check URL Exclusions

Some URLs are automatically excluded:

• chrome:// pages
• Login pages
• Banking sites
• Healthcare portals

Visit a regular website to test.

Verify Settings

// Check settings in DevTools console
chrome.storage.local.get(['priv_settings'], console.log);

Expected output:

{
  "dataSharingEnabled": true,
  "enabledDataTypes": ["browsing_history", ...]
}

Data Not Submitting

Symptom: Data collected but not sent

Solutions:

1. Check Internet Connection

   • Verify you're online
   • Try visiting api.privprotocol.xyz

2. Force Data Sync

   // Send via DevTools
   chrome.runtime.sendMessage({ type: 'FLUSH_QUEUE' });

3. Check for API Errors

   • Inspect service worker
   • Look for network errors in DevTools

4. Clear Queue

   chrome.storage.local.remove(['priv_queue']);

Earnings Not Updating

Balance Shows 0

Symptom: No earnings despite active data sharing

Possible Causes:

1. New Account: Earnings take time to accumulate
2. API Issues: Server might be down
3. Cache Stale: Data not refreshed

Solutions:

1. Click refresh button in extension
2. Wait 5 minutes for cache to update
3. Check API status

Force Cache Refresh

// Clear earnings cache
chrome.storage.local.remove([
  'priv_earnings_cache',
  'priv_balance_cache'
]);

// Request fresh data
chrome.runtime.sendMessage({ type: 'GET_EARNINGS' });

Pending Balance Not Converting

Symptom: Pending balance not moving to available

Explanation: Pending earnings are processed in batches.

• Processing time: 24-48 hours
• Minimum threshold: May need minimum amount
• Aggregation delay: Data must be aggregated first

Claim Button Disabled

Symptom: Cannot claim available earnings

Requirements:

Solutions:

1. Check you have 10+ PRIV available
2. Ensure wallet is connected
3. Switch to Base network in wallet

Performance Issues

Extension Slowing Browser

Symptom: Browser becomes slow with extension enabled

Solutions:

1. Reduce Data Types

   • Disable unnecessary data types
   • Focus on high-value categories

2. Check Memory Usage

   chrome://extensions
   Details > Memory: XX MB

3. Clear Collected Data

   chrome.storage.local.remove(['priv_collected_data']);

4. Update Extension

   • Check for newer versions
   • Rebuild if using development build

High Memory Usage

Symptom: Extension using >100MB memory

Causes:

• Large data queue
• Stale cached data
• Memory leaks (rare)

Solutions:

1. Force data submission:

   chrome.runtime.sendMessage({ type: 'FLUSH_QUEUE' });

2. Clear all storage:

   chrome.storage.local.clear();

3. Reload extension

UI Issues

Popup Not Rendering

Symptom: Blank or broken popup

Solutions:

1. Reload Extension

   • chrome://extensions
   • Click reload icon

2. Check Console Errors

   • Right-click extension icon
   • "Inspect popup"
   • Check Console tab

3. Clear React State

   chrome.storage.local.remove(['priv_settings']);

Dark Mode Issues

Symptom: Colors wrong or unreadable

Solutions:

• Extension follows system theme
• Check OS dark mode setting
• Force refresh popup

Charts Not Displaying

Symptom: Earnings history chart blank

Causes:

• No data yet
• Data format issue

Solutions:

1. Wait for data to accumulate (7 days)
2. Check weekly earnings data:

   chrome.runtime.sendMessage(
     { type: 'GET_EARNINGS' },
     (r) => console.log(r.data.weeklyEarnings)
   );

Network Errors

API Connection Failed

Symptom: "Failed to connect" errors

Solutions:

1. Check Internet

   • Visit other websites
   • Try api.privprotocol.xyz in browser

2. Check Firewall

   • Allow Chrome through firewall
   • Check VPN settings

3. DNS Issues

   • Try different DNS (8.8.8.8)
   • Flush DNS cache

Rate Limited

Symptom: "Too many requests" error

Solution: Wait before retrying

CORS Errors

Symptom: Network requests blocked

Note: Should not happen in normal use

If occurring:

1. Check you have correct extension version
2. API endpoint might have changed
3. Report as bug

Development Issues

Build Failures

Symptom: npm run build fails

Common Causes:

1. Missing Dependencies

   rm -rf node_modules
   npm install

2. TypeScript Errors

   npm run typecheck

3. Node Version

   node --version  # Should be 18+
   nvm use 18

Hot Reload Not Working

Symptom: Changes not reflecting

Solutions:

1. Ensure npm run dev is running
2. Manually reload extension
3. Hard refresh popup (Cmd+Shift+R)

Service Worker Not Updating

Symptom: Old code still running

Solutions:

1. Go to chrome://extensions
2. Click "Update" button
3. Or toggle extension off/on
4. Check service worker in DevTools

Diagnostic Commands

Check Extension State

Open background service worker DevTools and run:

// Get all storage data
chrome.storage.local.get(null, console.log);

// Get settings
chrome.storage.local.get(['priv_settings'], console.log);

// Get queue size
chrome.storage.local.get(['priv_queue'], (r) => {
  console.log('Queue entries:', r.priv_queue?.length ?? 0);
});

// Get cached data
chrome.storage.local.get([
  'priv_earnings_cache',
  'priv_balance_cache'
], console.log);

Reset Extension

Complete reset (loses all data):

// Clear all data
chrome.storage.local.clear(() => {
  console.log('Storage cleared');
});

// Reload extension
chrome.runtime.reload();

Test API Connection

fetch('https://api.privprotocol.xyz/health')
  .then(r => r.json())
  .then(console.log)
  .catch(console.error);

Getting Help

Before Asking for Help

1. Check this troubleshooting guide
2. Search existing GitHub issues
3. Gather diagnostic information

Information to Provide

When reporting issues, include:

• Chrome version
• Extension version
• Error messages (screenshots)
• Steps to reproduce
• Console logs (redact sensitive data)

Support Channels

Next Steps

• Installation - Reinstall if needed
• Development - Debug tools
• How It Works - Understand architecture