Skip to main content

​
Common Issues

​
Agent Not Detected

Problem: Agent is active but ContextFort isn’t tracking it.Solution:
  1. Ensure you’re using the correct emoji: ⌛ (hourglass)
  2. The emoji must be in the tab group title (Right-click tab → Add tab to group → Name with ⌛)
  3. Tab must be inside the grouped tab, not adjacent to it
  4. Try removing and re-adding the ⌛ emoji
Verification:
# Check the extension console
1. Right-click extension icon → Inspect service worker
2. Look for "swapping to agent" in console logs
Make sure there are no spaces or other characters before the emoji in the tab group name.
Problem: No session appears in the dashboard after starting agent.Solution:
1

Verify Tab Group

Ensure the tab is actually in a tab group (tab should have colored header)
2

Check Extension Permissions

  • Go to chrome://extensions
  • Find ContextFort
  • Verify all permissions are enabled
  • Click “Site access” → “On all sites”
3

Reload Extension

  • Go to chrome://extensions
  • Click the refresh icon on ContextFort
  • Reload the agent tab
4

Check Storage

  • Right-click extension icon → Inspect service worker
  • Console: chrome.storage.local.get(['sessions'], console.log)
  • Verify sessions array exists
Problem: ContextFort automatically ungrouping extra tabs.This is intentional behavior. ContextFort restricts agent sessions to one tab per group to maintain clean session tracking.Workaround:
  • Create separate tab groups for each agent session
  • Use Chrome’s native tab management for non-agent tabs

​
Screenshot Issues

Problem: Agent actions aren’t generating screenshots.Possible Causes:
  1. Tab not visible: Screenshots only work on active, visible tabs
    • Solution: Ensure agent tab is focused and not minimized
  2. Storage quota exceeded: Chrome has storage limits
    • Solution: Clear old screenshots from dashboard
    • Check: chrome://quota-internals
  3. Permissions issue: Extension can’t access tab content
    • Solution: Grant “On all sites” permission
  4. Content script not loaded: Script injection failed
    • Solution: Reload the tab after starting agent mode
Debug:
// Check if content script is loaded
// In page console (F12):
chrome.runtime.sendMessage({type: 'PING'}, (response) => {
  console.log('Content script loaded:', response);
});
Problem: Screenshots appear as blank images or fail to load.Solutions:
Blank screenshots usually indicate timing issues:
  1. Page still loading: Screenshot captured before render
    • Extension waits 300-500ms, but complex pages may need more time
  2. GPU acceleration issue:
    • Try disabling hardware acceleration: chrome://settings/system
    • Uncheck “Use hardware acceleration when available”
  3. CSP blocking:
    • Some sites block screenshot APIs
    • Check browser console for CSP errors
Problem: Screenshots captured but not visible in dashboard.Checklist:
  • Refresh the dashboard page
  • Check browser console for errors (F12)
  • Verify screenshots exist in storage: 
    chrome.storage.local.get(['screenshots'], (result) => {
  console.log('Screenshots:', result.screenshots?.length);
});
  • Try exporting and re-importing session data
  • Clear dashboard cache and reload

​
Session Isolation Problems

Problem: Agent session keeps getting cleared/logged out.This usually means:
  1. No saved agent session for that domain
    • You need to log in manually when prompted
    • Click “I’ve Logged In” after logging in with agent credentials
  2. Cookies expired
    • Agent session was saved but cookies expired
    • Log in again and save new session
  3. Cookie mismatch
    • Human session has different cookies than agent expects
    • Extension detects missing cookies and requires re-login
Solution:
1

Wait for Login Prompt

When agent starts, if no session exists, you’ll see login notification
2

Click 'Ok, I'll log in'

This clears cookies and prepares for agent login
3

Log In Manually

Use the agent’s credentials to log into the site
4

Click 'I've Logged In'

This saves the agent session for future use
The extension compares cookie names between human and agent sessions. If the agent session is missing cookies that the human session has, it requires re-login for safety.
Problem: Human session appears when agent should be active (or vice versa).Causes:
  1. Pending login in progress
    • Extension won’t swap sessions during login flow
    • Wait for login to complete
  2. Session swap failed
    • Check console for errors
    • Try stopping and restarting agent
  3. Subdomain issues
    • Cookies may be domain-specific
    • Agent session saved for app.example.com won’t work on example.com
Manual Fix:
// View stored sessions
chrome.runtime.sendMessage(
  {type: 'VIEW_STORED_SESSIONS'}, 
  console.log
);

// Delete problematic session
chrome.runtime.sendMessage({
  type: 'DELETE_SESSION_PROFILE',
  domain: 'example.com',
  profileType: 'agent'
});
Problem: Old cookies persist after session swap.Solutions:
  1. Clear all cookies manually:
    • chrome://settings/cookies/detail?site=example.com
    • Remove all cookies
    • Restart agent session
  2. Check for httpOnly cookies:
    • Some cookies can’t be accessed by extensions
    • May require manual browser logout
  3. Incognito mode workaround:
    • Run agent in incognito window
    • Note: Requires enabling extension in incognito

​
Blocking Not Working

Problem: Agent can still interact with blocked elements.Debugging Steps:
1

Verify Block Rule

Check dashboard → Controls → Blocked Actions
  • Ensure rule exists
  • Verify element selectors match
2

Check Element Details

Right-click element → Inspect:
  • Tag name
  • ID
  • Class name
  • Text content
Must exactly match what you blocked.
3

Test Manually

With agent stopped, try clicking element yourself
  • Should show red border
  • Should not trigger action
  • Should show “Action Blocked” notification
4

Check Console

F12 → Console:
  • Look for “ACTION_BLOCKED” messages
  • Verify event listeners are active
Element blocking only works if content script is loaded. If agent navigates too quickly, content script may not inject in time.
Problem: Agent can visit blocked URL combinations.Checklist:
  1. Check blocking rules:
    • Dashboard → Controls → URL Blocking
    • Verify domains are correct (no http:// prefix)
  2. Understand domain matching:
    • example.com matches example.com and *.example.com
    • Case-insensitive
    • Matches subdomains
  3. URL vs Domain blocking:
    • Domain blocking: Works on any page of that domain
    • URL pair blocking: Must be exact URL match
  4. Check visited URLs:
    • Dashboard → Session details → Visited URLs
    • Verify URLs match your expectations
Test blocking:
// In extension service worker console
// Get current session
chrome.storage.local.get(['sessions'], (result) => {
  console.log('Sessions:', result.sessions);
  console.log('Visited URLs:', result.sessions[0]?.visitedUrls);
});
Problem: DNR rules (disallow clickable URLs, query params) not working.Solutions:
  1. Check DNR rules are active: 
    // In extension console
chrome.declarativeNetRequest.getDynamicRules(console.log);
  2. Verify rule IDs:
    • 1000 = disallow_clickable_urls
    • 1001 = disallow_query_params
  3. DNR limitations:
    • Only blocks navigations from extension context
    • May not block agent if agent uses special navigation methods
  4. Alternative approach:
    • Use URL blocking instead of governance rules
    • More reliable but less performant

​
Storage Issues

Problem: Extension stops working, error about storage limits.
Chrome’s chrome.storage.local has a quota. Screenshots are base64-encoded and consume significant space.
Immediate Fix:
  1. Clear old screenshots: 
    chrome.storage.local.set({screenshots: []});
  2. Clear old sessions: 
    chrome.storage.local.get(['sessions'], (result) => {
  const activeSessions = result.sessions.filter(s => s.status === 'active');
  chrome.storage.local.set({sessions: activeSessions});
});
  3. Check current usage:
    • Visit chrome://quota-internals
    • Find ContextFort extension ID
    • View storage usage
Long-term Prevention:
  • Use dashboard export feature before clearing
  • Regularly delete old sessions
  • Limit agent session length
  • ContextFort keeps max 100 screenshots automatically
Problem: Extension behaves erratically, data looks wrong.Nuclear Option - Reset Everything:
This will delete all sessions, screenshots, and settings. Export important data first.
// In extension service worker console
chrome.storage.local.clear(() => {
  console.log('Storage cleared');
  chrome.runtime.reload(); // Reload extension
});
Selective Reset:
// Clear only specific data
chrome.storage.local.remove(['screenshots'], () => {
  console.log('Screenshots cleared');
});

chrome.storage.local.remove(['sessionProfiles'], () => {
  console.log('Session profiles cleared');
});
Problem: Changes in dashboard not reflecting in extension.
ContextFort does NOT use Chrome sync storage. All data is local to your machine.
If dashboard changes aren’t applying:
  1. Reload the dashboard page
  2. Check for browser console errors
  3. Verify extension is running:
    • Go to chrome://extensions
    • ContextFort should be enabled
    • Click “Inspect service worker” to check for errors
  4. Storage event listeners:
    • Extension listens for chrome.storage.onChanged
    • Some changes may require stopping and restarting agent

​
Performance Issues

​
Extension Slowing Down Browser

Symptoms:
  • Chrome becomes sluggish
  • High CPU usage
  • Tabs freezing
Solutions:
  1. Reduce screenshot frequency:
    • Extension captures on every click/input
    • High agent activity = many screenshots
    • Consider pausing agent periodically
  2. Clear old data regularly:
    • Export sessions before deleting
    • Keep only active sessions
  3. Check for conflicts:
    • Disable other extensions temporarily
    • Some privacy extensions conflict with ContextFort
  4. Monitor memory usage:
    • Chrome Task Manager: Shift+Esc
    • Look for “ContextFort” process
    • Reload extension if memory is high

​
Screenshots Taking Too Long

Problem: Noticeable delay after agent actions. Optimizations:
  • Hardware acceleration: Enable in chrome://settings/system
  • Close unused tabs: Each tab consumes memory
  • Reduce page complexity: Agent on simpler pages captures faster
  • SSD vs HDD: Storage writes faster on SSD

​
Getting Help

If you’ve tried everything and still have issues:
1

Collect Debug Information

  • Chrome version: chrome://version
  • Extension version: chrome://extensions
  • Console errors: Right-click extension → Inspect service worker
  • Page console errors: F12 on agent tab
2

Create Minimal Reproduction

  • Disable all other extensions
  • Test on a simple website
  • Note exact steps to reproduce
3

Report Issue

Visit GitHub IssuesInclude:
  • Description of problem
  • Steps to reproduce
  • Expected vs actual behavior
  • Debug information from Step 1
  • Screenshots if relevant
For security issues, please email security@contextfort.com instead of posting publicly.

Build docs developers (and LLMs) love

Get started for freeTalk to us