Skip to content

Troubleshooting

Jump to bottom
Wei Xuan edited this page Feb 7, 2026 · 1 revision

Troubleshooting

Solutions to common issues with Web Guide.

Quick Diagnostics

Before diving into specific issues, try these quick fixes:

  1. Refresh the page - Many issues are resolved by reloading
  2. Restart the extension - Toggle it off/on in chrome://extensions
  3. Check permissions - Ensure microphone access is granted
  4. View console - Right-click page → Inspect → Console for errors
  5. Test on a simple page - Try Wikipedia to isolate the issue

Installation Issues

Extension Won't Load

Symptoms:

  • "Failed to load extension" error
  • Extension card doesn't appear
  • No icon in toolbar

Solutions:

✅ Check file structure

Effin-IEEE-WebGuide-main/
├── manifest.json  ← Must be in root
├── popup.html
├── popup.js
└── ...

✅ Verify manifest.json

  • File must be valid JSON (use a JSON validator)
  • No syntax errors
  • All referenced files exist

✅ Enable Developer Mode

  • chrome://extensions
  • Toggle "Developer mode" in top-right

✅ Check Chrome version

  • Must be Chrome 88 or higher
  • Update Chrome if needed

✅ Remove and reload

1. Click "Remove" on extension
2. Click "Load unpacked" again
3. Select folder

Extension Loads But Icon Missing

Symptoms:

  • Extension appears in chrome://extensions
  • No icon in toolbar

Solutions:

✅ Pin the extension

1. Click puzzle piece icon in toolbar
2. Find "Web Guide"
3. Click pin icon

✅ Check icon files exist

icons/
├── icon16.png
├── icon48.png
└── icon128.png

✅ Restart Chrome

Permission Errors

Symptoms:

  • "Cannot access chrome:// URLs"
  • "Extension is not allowed on this page"

Solutions:

✅ These pages are blocked by design:

  • chrome:// pages (settings, extensions)
  • chrome-extension:// pages
  • Chrome Web Store pages

✅ For other pages:

  • Check manifest.json has "host_permissions": ["<all_urls>"]
  • Reload extension after manifest changes

Voice Input Issues

Microphone Not Working

Symptoms:

  • "Microphone permission denied"
  • No voice recognition
  • Button doesn't activate

Solutions:

✅ Grant microphone permission

1. Click lock icon in address bar
2. Find "Microphone"
3. Set to "Allow"
4. Refresh page

✅ Check browser permissions

chrome://settings/content/microphone
→ Ensure not blocked

✅ Test microphone in other apps

  • Verify hardware works
  • Check system audio settings
  • Try different browser

✅ Check for HTTPS

  • Voice API requires secure context
  • Use HTTPS sites (not HTTP)

Voice Recognition Inaccurate

Symptoms:

  • Commands transcribed incorrectly
  • Random words recognized
  • Poor accuracy

Solutions:

✅ Improve audio conditions

  • Reduce background noise
  • Speak clearly and at normal pace
  • Position microphone closer

✅ Check language settings

// In popup.js, ensure:
recognition.lang = 'en-US'; // Or your language

✅ Use simpler commands

  • "Find search bar" instead of "Where's the search?"
  • Short, clear phrases
  • Avoid complex sentences

Voice Output Not Working

Symptoms:

  • No audio from text-to-speech
  • Silent responses

Solutions:

✅ Check audio output

  • System volume not muted
  • Browser not muted in system mixer
  • Audio device connected

✅ Test Speech Synthesis

// In browser console:
speechSynthesis.speak(new SpeechSynthesisUtterance('Test'));

✅ Verify feature enabled

// In config.js:
const VOICE_OUTPUT = true;

API Issues

API Calls Failing

Symptoms:

  • "Failed to get response"
  • Loading spinner never stops
  • Console errors about fetch

Solutions:

✅ Check API key

// In config.js:
const GROQ_API_KEY = 'gsk_...'; // Must start with 'gsk_'

✅ Test API key manually

curl https://api.groq.com/openai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"llama-3.3-70b-versatile","messages":[{"role":"user","content":"test"}]}'

✅ Check Groq API status

✅ Verify network connection

// In browser console:
fetch('https://api.groq.com/openai/v1/models')
  .then(r => r.json())
  .then(console.log)
  .catch(console.error);

✅ Check CORS issues

  • Groq API should allow browser requests
  • If blocked, consider backend proxy

Rate Limit Errors

Symptoms:

  • "Rate limit exceeded"
  • 429 status code
  • API works then stops

Solutions:

✅ Wait and retry

  • Free tier has limits (check Groq docs)
  • Wait a few minutes
  • Try again

✅ Upgrade API plan

  • Free tier: limited requests/day
  • Paid tier: higher limits

✅ Implement request throttling

// Add debouncing to avoid rapid requests
let lastRequestTime = 0;
const MIN_REQUEST_INTERVAL = 2000; // 2 seconds

async function callAPI() {
  const now = Date.now();
  if (now - lastRequestTime < MIN_REQUEST_INTERVAL) {
    throw new Error('Please wait before next request');
  }
  lastRequestTime = now;
  // ... make request
}

Element Highlighting Issues

Elements Not Highlighting

Symptoms:

  • No visual feedback
  • AI responds but nothing highlights
  • "Element not found" in console

Solutions:

✅ Check element exists

// In console:
document.querySelector(selector); // Returns element or null

✅ Verify selector format

// Valid selectors:
'#search-input'           // ✅ ID
'.btn-primary'            // ✅ Class
'button[type="submit"]'   // ✅ Attribute
'div > a:first-child'     // ✅ Complex

// Invalid:
'search input'            // ❌ Space without combinator
'#my-id#other-id'         // ❌ Multiple IDs

✅ Check for dynamic content

  • Element may load after script runs
  • Try refreshing page
  • Wait for page to fully load

✅ Check for Shadow DOM

// Shadow DOM elements not accessible via querySelector
// Currently limited support

✅ Inspect CSS injection

// Verify content.css is loaded:
const style = document.querySelector('link[href*="content.css"]');
console.log('CSS loaded:', !!style);

Highlight Positioned Incorrectly

Symptoms:

  • Arrow points to wrong place
  • Highlight offset from element
  • Tooltip in wrong position

Solutions:

✅ Check for CSS transforms

/* Parent transforms can affect positioning */
.parent {
  transform: scale(1.1); /* May offset calculations */
}

✅ Scroll and retry

  • Manually scroll element into view
  • Try command again

✅ Check viewport size

  • Resize browser window
  • Try on different screen resolution

✅ Check z-index conflicts

/* Ensure high z-index */
.webguide-highlight {
  z-index: 999999 !important;
}

Can't Dismiss Highlights

Symptoms:

  • Clicking doesn't remove highlight
  • Highlights persist
  • Multiple highlights stack

Solutions:

✅ Click outside highlighted element

  • Click page background
  • Click empty space

✅ Manually clear

// In console:
document.querySelectorAll('.webguide-arrow, .webguide-tooltip, .webguide-highlight')
  .forEach(el => el.remove());

✅ Refresh page

  • Ultimate reset
  • Clears all highlights

Page-Specific Issues

Not Working on Specific Sites

Symptoms:

  • Works on most sites
  • Fails on certain domains
  • Console errors on specific pages

Solutions:

✅ Check for content security policy (CSP)

// Some sites block injected scripts
// Check console for CSP errors

✅ Check for iframe restrictions

// Extension can't access cross-origin iframes
// Some embedded content may be inaccessible

✅ Sites with known issues:

  • Gmail (heavy use of Shadow DOM)
  • Google Docs (complex iframe structure)
  • Banking sites (CSP restrictions)

✅ Workarounds:

  • Refresh page after it loads
  • Wait longer before using extension
  • Try on simpler pages on same domain

Single-Page Apps (SPAs)

Symptoms:

  • Works on initial load
  • Breaks when navigating
  • Stale page data

Solutions:

✅ Refresh after navigation

  • SPAs don't reload content script
  • Manual refresh may be needed

✅ Wait for content to load

  • Dynamic content takes time
  • Wait before issuing commands

✅ Future enhancement:

// Monitor URL changes
let lastUrl = location.href;
setInterval(() => {
  if (location.href !== lastUrl) {
    lastUrl = location.href;
    reinitialize();
  }
}, 1000);

Performance Issues

Extension Slowing Down Browser

Symptoms:

  • Pages load slowly
  • High CPU/memory usage
  • Browser freezes

Solutions:

✅ Check for memory leaks

// In chrome://extensions → inspect background page
// Look for growing memory usage

✅ Clear highlights regularly

// Add auto-cleanup
setInterval(() => {
  VisualGuide.clearHighlights();
}, 10000); // Every 10 seconds

✅ Limit element extraction

// In content.js, reduce MAX_ELEMENTS:
const MAX_ELEMENTS = 50; // Instead of 100

✅ Disable unused features

// In config.js:
const VOICE_OUTPUT = false; // If not needed

Slow API Responses

Symptoms:

  • Long wait times
  • Timeout errors
  • Loading state persists

Solutions:

✅ Check network speed

  • Test internet connection
  • Try on faster network

✅ Reduce prompt size

// Truncate page text more aggressively
const MAX_PAGE_TEXT = 2000; // Instead of 5000

✅ Use faster model

// In config.js:
const GROQ_MODEL = 'llama-3.1-8b-instant'; // Faster, less accurate

Browser Console Errors

Common Error Messages

"Cannot read property of undefined"

Cause: Trying to access property on null/undefined object

Fix:

// Before:
const text = element.textContent;

// After:
const text = element?.textContent || '';

"Failed to execute 'postMessage' on 'DOMWindow'"

Cause: Trying to message between different origins

Fix:

// Ensure proper origin checking
if (event.origin !== window.location.origin) return;

"Extension context invalidated"

Cause: Extension reloaded while page open

Fix:

  • Refresh the page
  • Reload extension less frequently

"WebSocket connection failed"

Cause: Network issue or API endpoint down

Fix:

  • Check internet connection
  • Verify API status
  • Check firewall/proxy settings

Getting More Help

Enable Debug Mode

Add this to config.js:

const DEBUG = true;

function debug(...args) {
  if (DEBUG) console.log('[WebGuide Debug]', ...args);
}

Collect Diagnostic Info

When reporting issues, include:

1. Browser: Chrome 120.0.6099.129
2. OS: Windows 11
3. Extension version: 1.0.0
4. URL where issue occurs: https://example.com
5. Steps to reproduce:
   - Step 1
   - Step 2
   - Step 3
6. Console errors: [paste here]
7. Expected behavior: [describe]
8. Actual behavior: [describe]

Report Bugs

If you can't resolve the issue:

  1. Check existing issues
  2. Create new issue with diagnostic info
  3. Include screenshots if applicable
  4. Tag with appropriate label

Community Support

Prevention Tips

Best Practices

✅ Keep extension updated

  • Watch for new releases
  • Read changelog before updating

✅ Test before relying on it

  • Try on test sites first
  • Verify functionality

✅ Monitor API usage

  • Track requests if on free tier
  • Set up usage alerts

✅ Backup your configuration

# Save your config.js
cp config.js config.backup.js

✅ Use version control

git init
git add .
git commit -m "Working state"

← Back to FAQ | Home →

Clone this wiki locally