Skip to main content

​
Installation Issues

​
Cannot Load Unpacked Extension

Problem: Chrome rejects loading the extension with error message Solutions:
  1. Verify Developer Mode: Ensure “Developer mode” toggle is ON in chrome://extensions
  2. Check Manifest: Confirm the folder contains manifest.json at the root level
  3. Folder Selection: Ensure you selected the extracted folder, NOT the .zip file
  4. Chrome Version: Verify Chrome is version 88 or higher (check chrome://settings/help)
  5. Clean Extraction: Re-extract the .zip file to a new folder and try again

​
”This extension may have been corrupted”

Problem: Chrome displays corruption warning Solutions:
  1. Delete the extracted folder completely
  2. Re-download the extension package from Desktop or administrator
  3. Extract to a new location
  4. Verify the .zip file is not corrupted (check file size matches expected)
  5. Temporarily disable antivirus during extraction
  6. Try loading the extension again

​
Extension Immediately Disabled After Loading

Problem: Extension disables itself automatically after installation Solutions:
  1. Check Enterprise Policies: Visit chrome://policy to see if organization policies restrict extensions
  2. Contact IT Admin: Request whitelist approval for Qaptly Browser Pilot
  3. Antivirus Interference: Check if antivirus software is blocking the extension
  4. Chrome Sync: Disable Chrome sync temporarily and try again
  5. Clean Profile: Try installing in a new Chrome profile (Settings → Manage profiles → Add)

​
Side Panel Won’t Open

Problem: Clicking the extension icon has no response Solutions:
  1. Reload Extension: Go to chrome://extensions and click the reload icon (circular arrow) for Qaptly Browser Pilot
  2. Check Chrome Version: Side Panel API requires Chrome 114+. Update Chrome if needed.
  3. Restart Browser: Close all Chrome windows completely and restart
  4. Check Service Worker: In chrome://extensions, click “Service worker” link to see error logs
  5. Reinstall Extension: Remove and reinstall the extension

​
Extension Icon Missing from Toolbar

Problem: Cannot find the Qaptly icon after installation Solutions:
  1. Click the puzzle icon (Extensions menu) in toolbar
  2. Find “Qaptly Browser Pilot” in the list
  3. Click the pin icon to add it to toolbar
  4. If not in list, verify extension is enabled in chrome://extensions

​
Connection Issues

​
Cannot Connect to Desktop

Problem: Side Panel shows “Disconnected” and clicking “Connect” fails Solutions:
  1. Verify Desktop Running: Ensure Qaptly Desktop application is launched
  2. Check Pilot Service: In Desktop, navigate to Pilot Control and verify Browser Pilot service is enabled
  3. Port Availability: Ensure no other application is using port 8080
    • Windows: Run netstat -ano | findstr :8080 in Command Prompt
    • Mac/Linux: Run lsof -i :8080 in Terminal
  4. Firewall Settings: Check that firewall allows localhost connections on port 8080
  5. Restart Both: Restart both Desktop application and Chrome browser
  6. Check Logs: View Desktop application logs for WebSocket errors

​
Connection Drops Frequently

Problem: Connection status switches between Connected and Disconnected Solutions:
  1. System Resources: Close unnecessary applications to free up memory and CPU
  2. Network Issues: Check for network connectivity problems
  3. Desktop Stability: Ensure Desktop application is not crashing or freezing
  4. Chrome Updates: Update Chrome to the latest version
  5. Extension Reload: Reload the extension in chrome://extensions
  6. Port Conflicts: Verify no other service is intermittently using port 8080

​
Data Not Reaching Desktop

Problem: Extension shows “Connected” but Desktop doesn’t receive data Solutions:
  1. Verify Connection: Check Desktop shows the browser client in connected devices list
  2. Client Name: Look for client name like chrome_a1B2c3D4e5F6 in Desktop
  3. Test Recording: Toggle tracking on/off and perform actions to generate events
  4. Desktop Logs: Check Desktop logs for incoming WebSocket messages
  5. Reconnect: Click “Connect” button again to re-establish connection
  6. Browser Console: Open DevTools (F12) on Side Panel and check Console for errors

​
WebSocket Connection Failed Error

Problem: Console shows “WebSocket connection to ‘ws://localhost:8080’ failed” Solutions:
  1. Desktop WebSocket Service: Verify the WebSocket server is running in Desktop
  2. Correct Port: Confirm Desktop is listening on port 8080 (check Desktop settings)
  3. Localhost Resolution: Test if localhost resolves correctly:
  4. IPv6 Issues: Try using 127.0.0.1 instead of localhost (requires Desktop configuration)
  5. VPN/Proxy: Disable VPN or proxy that might interfere with localhost
  6. Hosts File: Verify C:\Windows\System32\drivers\etc\hosts (Windows) or /etc/hosts (Mac/Linux) has correct localhost entry

​
Recording Issues

​
Events Not Being Captured

Problem: User actions don’t appear in statistics or aren’t sent to Desktop Solutions:
  1. Tracking Enabled: Verify “Enable tracking” toggle is ON in Monitor tab
  2. Connected Status: Ensure Side Panel shows “Connected” status
  3. Supported Pages: Confirm you’re on an http:// or https:// page (not chrome://)
  4. Page Reload: Reload the webpage and enable tracking again
  5. Console Errors: Check browser console (F12) for JavaScript errors
  6. Extension Reload: Reload extension in chrome://extensions

​
Some Clicks Not Recorded

Problem: Certain buttons or elements don’t capture click events Solutions:
  1. Element Type: Some custom elements or shadow DOM elements have limited access
  2. Event Timing: Click might occur during page navigation (too fast to capture)
  3. iframes: Clicks inside cross-origin iframes cannot be captured
  4. Canvas Elements: Clicks on canvas-drawn buttons aren’t detectable
  5. JavaScript Handlers: Some event handlers might prevent bubbling

​
Input Text Not Captured

Problem: Text typing not recorded in form fields Solutions:
  1. Input Method: Ensure you’re typing, not pasting (paste events may not trigger properly)
  2. Field Type: Some custom input components (rich text editors) have limitations
  3. Auto-Complete: Browser auto-complete might bypass input event listeners
  4. Timing: Type at normal speed; very fast typing might miss events

​
Mouse Move Events Missing

Problem: Mouse movements not captured in statistics Solutions:
  1. Monitor Level: Mouse move capture is disabled by default (Level 1)
  2. Desktop Configuration: Desktop must enable mouse move tracking explicitly
  3. Performance: Mouse moves are disabled for performance reasons in most cases
  4. Check Level: Verify current monitor level in analysis results

​
Page Analysis Issues

​
Analysis Fails or Times Out

Problem: Clicking “Analyze” button shows error or never completes Solutions:
  1. Page Complexity: Very complex pages (5000+ elements) may timeout
  2. Wait for Load: Ensure page is fully loaded before analyzing
  3. JavaScript Errors: Page errors may interfere with analysis
  4. Extension Debugger: Check if Chrome debugger permission is granted
  5. Try Simplified Page: Test on a simpler page first to verify extension works
  6. Increase Timeout: Contact support if consistent timeout on normal pages

​
Elements Not Detected

Problem: Expected elements don’t appear in analysis results Solutions:
  1. Visibility: Only visible elements are analyzed by default
  2. Interactive Filter: Level 1 monitoring filters out non-interactive elements (p, div, span)
  3. Dynamic Content: Elements loaded after initial analysis aren’t included
  4. Shadow DOM: Elements inside shadow DOM have limited detection
  5. iframe Content: Cross-origin iframe content cannot be analyzed

​
Mark/Highlight Not Showing

Problem: Clicking “Mark” button doesn’t highlight elements Solutions:
  1. Analyze First: Must click “Analyze” before using “Mark”
  2. CSP Restrictions: Page Content Security Policy may block injected styles
  3. Z-Index Issues: Highlights may be behind other elements
  4. Clear First: Click “Clear” then “Analyze” again
  5. Check Console: Look for CSP errors in browser console (F12)

​
Screenshot Capture Fails

Problem: Screenshots not captured during analysis Solutions:
  1. Tab Permission: Ensure extension has activeTab permission
  2. Incognito Mode: Screenshots may fail in incognito mode with restricted permissions
  3. Large Pages: Very large pages may hit memory limits
  4. Disk Space: Check available disk space
  5. Extension Reload: Reload extension and try again

​
Execution Issues

​
Actions Fail to Execute

Problem: Clicking “Execute” does nothing or actions fail Solutions:
  1. Connected Status: Verify connection to Desktop is active
  2. Action List Empty: Ensure Desktop has sent actions to execute
  3. Page Match: Confirm you’re on the correct page (URL must match recorded page)
  4. Element Not Found: Target elements may have changed since recording
  5. Page State: Ensure page is fully loaded before execution
  6. Console Errors: Check browser console for execution errors

​
Element Not Found Errors

Problem: Execution fails with “Element not found” messages Solutions:
  1. Page Changes: Website structure may have changed since recording
  2. Dynamic IDs: Elements with auto-generated IDs may differ between sessions
  3. Wait for Load: Page may not be fully loaded when action attempts execution
  4. Viewport Position: Element may be off-screen (try scrolling into view first)
  5. Different Environment: Test vs. production environment differences
  6. Re-record: Record the test again if page has significantly changed

​
Execution Too Slow or Too Fast

Problem: Actions execute at wrong pace Solutions:
  1. Desktop Configuration: Execution speed is controlled by Desktop application
  2. Wait Times: Desktop may need to adjust wait times between actions
  3. Page Performance: Slow page load times affect execution speed
  4. Network Latency: Poor network connection slows down navigation actions
  5. Contact Support: Request execution speed adjustment in Desktop settings

​
Visual Indicators Not Showing

Problem: Orange border or ripple effects don’t appear during execution Solutions:
  1. CSP Restrictions: Page Content Security Policy blocks injected styles
  2. Console Errors: Check console for CSP violation errors
  3. Z-Index Issues: Indicators may be behind other page elements
  4. Extension Version: Ensure you’re using latest extension version
  5. Functionality Still Works: Indicators are cosmetic; execution continues without them

​
Click Actions Don’t Work

Problem: Click actions execute but don’t trigger expected behavior Solutions:
  1. Element Loaded: Verify element exists and is visible before click
  2. Click Coordinates: Coordinates may be incorrect if viewport size changed
  3. Event Listeners: Some elements require specific event types (mousedown vs. click)
  4. Overlays: Modal or popup may be blocking the element
  5. JavaScript Required: Page may require JavaScript events that aren’t triggered

​
Performance Issues

​
Extension Running Slowly

Problem: Browser becomes sluggish with extension enabled Solutions:
  1. Disable When Idle: Turn off tracking when not actively recording
  2. Close Unused Tabs: Reduce memory pressure by closing tabs
  3. Disable Other Extensions: Temporarily disable other extensions to test
  4. Clear Browser Cache: Clear cache and browsing data
  5. Update Chrome: Ensure Chrome is up to date
  6. Restart Browser: Close all Chrome windows and restart

​
High Memory Usage

Problem: Chrome memory consumption increases significantly Solutions:
  1. Stop Tracking: Disable tracking when not in use
  2. Close Side Panel: Close panel when not needed to free resources
  3. Limit Recording Duration: Record in shorter sessions
  4. Check for Leaks: Open chrome://extensions, click “Service worker”, and monitor memory
  5. Extension Reload: Reload extension to clear accumulated data
  6. Report Issue: If persistent, report memory leak with details

​
Page Load Delays

Problem: Pages load slower with extension active Solutions:
  1. Content Script Overhead: Minimal overhead expected; extreme delays indicate issues
  2. Disable Tracking: Turn off tracking on pages you’re not testing
  3. Network Throttling: Check if network is slow (not extension-related)
  4. Page Complexity: Very complex pages naturally load slower
  5. Disable Extension: Temporarily disable to confirm extension is cause

​
Browser-Specific Issues

​
Chrome Enterprise Edition Restrictions

Problem: Enterprise policy prevents extension installation or usage Solutions:
  1. Check Policies: Visit chrome://policy and search for extension-related policies
  2. Contact IT: Request approval from IT administrator
  3. Whitelist Extension: Provide extension ID to IT for whitelist: [ID from manifest]
  4. Policy Documentation: Share Qaptly security documentation with IT
  5. Alternative Browser: Use personal Chrome profile or different machine if allowed

​
Microsoft Edge Compatibility

Problem: Extension behaves differently on Edge Solutions:
  1. Chromium-Based: Ensure using Chromium-based Edge (version 79+, icon is blue/green)
  2. Load in Edge: Install same extension in Edge (edge://extensions)
  3. Minor Differences: Some APIs may have slight differences; report issues
  4. Use Chrome: Switch to Chrome if persistent issues

​
Brave Browser Issues

Problem: Extension doesn’t work correctly in Brave Solutions:
  1. Shields Down: Disable Brave Shields for test websites
  2. Tracker Blocking: Brave’s aggressive blocking may interfere; whitelist localhost
  3. Fingerprinting Protection: Disable fingerprinting protection for testing
  4. Use Chrome: Brave compatibility is not officially supported; use Chrome

​
Conflicts with Other Extensions

Problem: Extension conflicts with ad blockers, privacy tools, or other extensions Solutions:
  1. Identify Conflict: Disable other extensions one-by-one to find culprit
  2. Ad Blockers: Whitelist test websites in ad blocker settings
  3. Privacy Extensions: Disable strict privacy extensions during testing
  4. Script Blockers: Whitelist localhost and test domains
  5. Testing Profile: Create separate Chrome profile with minimal extensions for testing

​
Error Messages

​
”Service Worker Inactive”

Cause: Extension’s background service worker has stopped Solutions:
  1. Go to chrome://extensions
  2. Find Qaptly Browser Pilot
  3. Click the reload icon (circular arrow)
  4. If error persists, click “Service worker” link to view error logs
  5. Reinstall extension if reload doesn’t fix issue

​
”Permission Denied”

Cause: Extension lacks required permissions for operation Solutions:
  1. Check permissions in chrome://extensions for Qaptly Browser Pilot
  2. Verify page is not restricted (not chrome:// or other internal page)
  3. Reload extension to re-request permissions
  4. Reinstall extension if permissions corrupted

​
”Failed to establish connection”

Cause: Side Panel cannot communicate with Service Worker Solutions:
  1. Reload extension in chrome://extensions
  2. Close and reopen Side Panel
  3. Restart Chrome completely
  4. Check Service Worker is running (click “Service worker” link in chrome://extensions)
  5. Review Service Worker console for errors

​
”Debugger already attached”

Cause: Another debugger (DevTools or extension) is attached to the tab Solutions:
  1. Close Chrome DevTools (F12) on the target page
  2. Disable other debugging extensions temporarily
  3. Reload the target page
  4. Try analysis/execution again

​
”Navigation interrupted”

Cause: Page navigation was interrupted during action execution Solutions:
  1. Ensure stable network connection
  2. Wait longer for page to load completely
  3. Check if page has redirects that interfere
  4. Verify target URL is correct and accessible

​
Content Security Policy (CSP) Issues

​
Visual Indicators Blocked

Problem: Console shows CSP violation errors for injected styles Solutions:
  1. Expected Behavior: Some security-focused sites block style injection
  2. Functionality Preserved: Recording and execution still work
  3. No Fix Available: CSP is a security feature; cannot override
  4. Report to Desktop: Desktop receives data despite missing visual feedback

​
Script Injection Blocked

Problem: Cannot inject tracking scripts into page Solutions:
  1. CSP Restrictions: Page has strict Content-Security-Policy headers
  2. Limitations Accepted: Some pages cannot be fully instrumented
  3. Partial Functionality: Basic recording may still work
  4. Test Environment: Use test environment with relaxed CSP if possible

​
Debug Procedures

​
Viewing Extension Logs

Service Worker Console:
  1. Go to chrome://extensions
  2. Enable “Developer mode”
  3. Find Qaptly Browser Pilot
  4. Click “Service worker” link (or “background page”)
  5. View console logs for errors
Side Panel Console:
  1. Right-click anywhere in Side Panel
  2. Select “Inspect”
  3. DevTools opens for Side Panel
  4. Check Console tab for errors
  5. Check Network tab for WebSocket connection
Content Script Console:
  1. Open DevTools on the target webpage (F12)
  2. Console may show messages from tracking.js
  3. Look for [Tracking] or [Monitor] prefixed messages

​
Collecting Debug Information

When reporting issues, provide:
  1. Chrome Version: chrome://settings/help
  2. Extension Version: Found in Advanced tab of Side Panel
  3. Operating System: Windows/Mac/Linux and version
  4. Error Messages: Screenshots or copy/paste from console
  5. Steps to Reproduce: Detailed steps to replicate the issue
  6. Console Logs: From Service Worker and Side Panel
  7. Desktop Logs: Relevant logs from Desktop application
  8. Network Tab: WebSocket connection status and messages

​
Testing Extension Isolation

To verify if extension is causing issues:
  1. Create new Chrome profile (Settings → Manage profiles → Add)
  2. Install only Qaptly Browser Pilot
  3. Test functionality
  4. If works: conflict with other extension
  5. If fails: extension or system issue

​
Getting Help

If problems persist after troubleshooting:
  1. Check Documentation: Review all documentation sections
  2. Update Everything: Ensure Chrome, extension, and Desktop are latest versions
  3. Collect Debug Info: Gather all information listed above
  4. Contact Support: Reach out with detailed issue description and debug info
  5. Community Forum: Check if others have encountered similar issues
Support Channels:
  • Email: [email protected]
  • Documentation: <host>
  • GitHub Issues: [Report technical issues]
Related Resources: