Skip to main content

Troubleshooting

Common issues and solutions when using DebuggAI.

Build & Setup Issues​

Project Won't Build​

Problem: Build fails or hangs indefinitely

Possible Causes:

  • Missing or outdated dependencies
  • Incompatible Node.js version
  • Corrupted node_modules

Solutions:

  1. Clear dependencies: rm -rf node_modules && npm install
  2. Verify Node.js version matches project requirements
  3. Check for build errors in terminal output
  4. Run npm cache clean --force and reinstall

Can't Connect to Localhost​

Problem: Application unreachable at localhost URL

Possible Causes:

  • Development server not running
  • Port already in use by another process
  • Tunnel not configured correctly

Solutions:

  1. Verify server is running: check terminal for startup confirmation
  2. Check port conflicts: lsof -i :PORT (macOS/Linux) or netstat -ano | findstr :PORT (Windows)
  3. Kill conflicting processes and restart
  4. If using tunnels (ngrok, localtunnel), verify tunnel is active and URL is current
  5. Check firewall isn't blocking the port

GitHub Integration Not Working​

Problem: Repository connection fails or webhooks don't fire

Possible Causes:

  • Insufficient GitHub permissions
  • Webhook misconfiguration
  • OAuth token expired

Solutions:

  1. Verify GitHub app has correct repository permissions
  2. Re-authorize the GitHub connection in settings
  3. Check webhook delivery status in GitHub repo settings
  4. Ensure webhook URL is accessible (not blocked by firewall)

Test Execution Issues​

Tests Timing Out​

Problem: Tests fail with timeout errors

Possible Causes:

  • Default timeout too short for slow operations
  • Network latency or slow server responses
  • Element not appearing in expected time

Solutions:

  1. Increase test timeout in settings
  2. Check network connectivity and server performance
  3. Add explicit waits for slow-loading elements
  4. Verify test environment has adequate resources

Tests Failing Intermittently​

Problem: Same test passes sometimes, fails other times

Possible Causes:

  • Race conditions in application
  • Flaky selectors or timing issues
  • External service dependencies

Solutions:

  1. Add proper wait conditions instead of fixed delays
  2. Use more stable selectors (data-testid over CSS classes)
  3. Mock external services for consistent behavior
  4. Check for animations/transitions that affect timing
  5. Run tests in isolation to identify conflicts

Screenshots Not Capturing​

Problem: Test results missing screenshots or captures are blank

Possible Causes:

  • Viewport configuration issues
  • Page not fully rendered when capture occurs
  • Browser permissions blocking capture

Solutions:

  1. Set explicit viewport dimensions in test config
  2. Add wait for page load completion before capture
  3. Check browser sandbox settings
  4. Verify test has sufficient wait time after navigation

Authentication Failing in Tests​

Problem: Tests can't log in or session expires mid-test

Possible Causes:

  • Test credentials invalid or expired
  • Session/cookie handling issues
  • CSRF token problems

Solutions:

  1. Verify test credentials are valid and active
  2. Configure proper cookie persistence between steps
  3. Use API-based authentication to set session before UI tests
  4. Check if 2FA is blocking automated login

Browser Agent Issues​

Agent Not Finding Elements​

Problem: Agent fails to locate UI elements

Possible Causes:

  • Selectors changed after UI update
  • Element loads asynchronously
  • Element inside iframe or shadow DOM

Solutions:

  1. Re-train agent on updated UI
  2. Use semantic selectors (labels, roles) over brittle CSS
  3. Add wait conditions for dynamic content
  4. Check if element is in iframe and adjust context

Agent Stuck in Loop​

Problem: Agent repeats same action or can't progress

Possible Causes:

  • Missing exit conditions
  • Ambiguous instructions
  • UI state not changing as expected

Solutions:

  1. Add explicit success/failure conditions to tasks
  2. Clarify task instructions with specific outcomes
  3. Add maximum retry limits
  4. Check if action is actually changing application state

Training Not Improving Accuracy​

Problem: Agent accuracy doesn't improve with more training

Possible Causes:

  • Training data quality issues
  • Insufficient diversity in examples
  • Conflicting or inconsistent training samples

Solutions:

  1. Review training data for accuracy and consistency
  2. Add diverse examples covering edge cases
  3. Remove duplicate or conflicting training samples
  4. Focus training on specific failure scenarios

Knowledge Graph Issues​

Crawl Not Discovering Pages​

Problem: Crawl completes but misses expected pages

Possible Causes:

  • Pages require authentication
  • Content rendered by JavaScript only
  • Links generated dynamically

Solutions:

  1. Provide authenticated session for crawl
  2. Enable JavaScript rendering in crawler settings
  3. Manually add entry points for JavaScript-rendered sections
  4. Check robots.txt isn't blocking crawler

Graph Showing Incomplete Data​

Problem: Knowledge graph missing nodes or relationships

Possible Causes:

  • Crawl depth limit reached
  • URL patterns excluded
  • Crawl interrupted before completion

Solutions:

  1. Increase crawl depth limit
  2. Review exclude patterns in crawl configuration
  3. Re-run crawl and monitor for errors
  4. Check crawl logs for skipped URLs and reasons

Account & Billing Issues​

Quota Exceeded​

Problem: Operations fail with quota/limit errors

Possible Causes:

  • Monthly usage limit reached
  • Concurrent test limit exceeded
  • Storage quota full

Solutions:

  1. Check current usage in account dashboard
  2. Wait for monthly reset (check reset date in billing)
  3. Upgrade plan for higher limits
  4. Delete old test data to free storage

Can't Access Features​

Problem: Features visible but disabled or returning errors

Possible Causes:

  • Feature not included in current plan
  • Trial period expired
  • Account permissions insufficient

Solutions:

  1. Review plan features in pricing page
  2. Upgrade plan to access feature
  3. Check if team admin has restricted access
  4. Contact support if feature should be available

Extension Installation Issues​

Extension Not Found in Marketplace​

Problem: Cannot find DebuggAI extension when searching

Solutions:

  • Ensure you're searching for "DebuggAI" (correct spelling)
  • Try searching for "debugg-ai" or "debugg ai"
  • Visit the direct marketplace link: VS Code Marketplace
  • Check your internet connection
  • Restart VS Code/Cursor completely

Extension Won't Install​

Problem: Installation fails or hangs

Solutions:

  • Check available disk space
  • Verify VS Code/Cursor version compatibility (VS Code 1.60+)
  • Clear extension cache: Close IDE → Delete ~/.vscode/extensions folder → Restart
  • Try manual installation with .vsix file
  • Check corporate firewall/proxy settings

Extension Commands Not Available​

Problem: DebuggAI commands don't appear in Command Palette

Solutions:

  • Verify extension is enabled: Extensions → DebuggAI → Enable
  • Reload window: Cmd+Shift+P → "Developer: Reload Window"
  • Check for extension updates
  • Look for error messages in Output → DebuggAI
  • Reinstall the extension

Authentication and Login Issues​

Cannot Sign In​

Problem: Login fails or hangs

Solutions:

  • Verify internet connection
  • Check your DebuggAI account credentials
  • Try signing up for a new account at app.debugg.ai
  • Clear stored credentials: Settings → Extensions → DebuggAI → Reset
  • Check corporate firewall blocking external authentication

Account Not Recognized​

Problem: Extension says account doesn't exist

Solutions:

  • Verify email address spelling
  • Check if you signed up with a different email
  • Try password reset on the web dashboard
  • Ensure account email is verified
  • Contact support at hello@debugg.ai

Authentication Token Expired​

Problem: Frequent re-login requests

Solutions:

  • Sign out and sign back in through Command Palette
  • Check system clock is correct
  • Update to latest extension version
  • Clear and re-enter credentials
  • Contact support if issue persists

Local Server Connection Issues​

Extension Can't Connect to Localhost​

Problem: Tests fail with connection errors

Solutions:

  • Verify server is running: Check your development server is active
  • Check port configuration: Ensure extension port matches your server
  • Test localhost manually: Visit http://localhost:PORT in browser
  • Check firewall settings: Ensure localhost connections are allowed
  • Try different port: Use a different port and update extension settings

Wrong Port Configuration​

Problem: Extension connects to wrong application

Solutions:

  • Check extension settings: Settings → Extensions → DebuggAI → Local Server Port
  • Verify server port: Check your development server startup logs
  • Update workspace settings: Add .vscode/settings.json with correct port
  • Restart extension: Reload window after changing port settings

Server Runs But Extension Can't Access​

Problem: Server is running but extension reports connection failure

Solutions:

  • Check localhost binding: Ensure server binds to 0.0.0.0 not just 127.0.0.1
  • Disable VPN: VPN software can interfere with localhost
  • Check Docker networking: If using Docker, ensure proper port mapping
  • Verify CORS settings: Some servers block external requests to localhost
  • Test with curl: curl http://localhost:PORT should work

Test Creation and Execution Issues​

Tests Fail to Create​

Problem: "Create New E2E Test" command fails

Solutions:

  • Check internet connection: Extension needs to communicate with DebuggAI servers
  • Verify account status: Ensure account is active and within usage limits
  • Check test description: Ensure description is clear and specific
  • Review server logs: Check for errors in development server console
  • Try simpler test: Start with basic test like "Test homepage loads"

Tests Run But Fail Immediately​

Problem: Tests start but fail within seconds

Solutions:

  • Check application state: Ensure app is fully loaded before testing
  • Verify URL accessibility: Manually test the URLs being accessed
  • Check for JavaScript errors: Look for console errors in browser
  • Review test description: Ensure test description matches actual app functionality
  • Check loading times: App might need more time to initialize

Tests Hang or Timeout​

Problem: Tests run indefinitely without completing

Solutions:

  • Increase timeout: Settings → Extensions → DebuggAI → Test Timeout
  • Check for loading states: App might be stuck in loading state
  • Verify network connectivity: Slow internet can cause timeouts
  • Check background processes: Other processes might be blocking resources
  • Review test complexity: Simplify test description and retry

Test Results and Output Issues​

No Test Results Displayed​

Problem: Tests complete but no results appear

Solutions:

  • Check Test Results panel: View → Test Results in VS Code
  • Look for notifications: Check for error notifications in IDE
  • Review Output panel: Output → DebuggAI for detailed logs
  • Verify account permissions: Ensure account can access test results
  • Check internet connection: Results might not sync without connection

Test Results Panel Empty​

Problem: Test Results panel shows no data

Solutions:

  • Refresh panel: Close and reopen Test Results panel
  • Restart extension: Cmd+Shift+P → "Developer: Reload Window"
  • Check test completion: Ensure tests actually completed successfully
  • Verify extension version: Update to latest version
  • Clear cache: Sign out and back in to refresh data

Screenshots or Recordings Missing​

Problem: Test results lack visual evidence

Solutions:

  • Check test execution: Ensure tests actually ran (didn't just simulate)
  • Verify account tier: Some features require Pro account
  • Check browser capabilities: Extension needs modern browser features
  • Review privacy settings: Browser might block screenshot capability
  • Test with simple page: Try testing a basic HTML page first

Performance and Resource Issues​

High CPU Usage​

Problem: DebuggAI extension causes high CPU usage

Solutions:

  • Check concurrent tests: Don't run multiple tests simultaneously
  • Review test complexity: Simplify complex test scenarios
  • Close unnecessary applications: Free up system resources
  • Update extension: Newer versions may have performance improvements
  • Contact support: Report performance issues with system details

Memory Issues​

Problem: IDE becomes slow or unresponsive

Solutions:

  • Restart IDE: Close and restart VS Code/Cursor
  • Check available RAM: Ensure sufficient memory available
  • Disable other extensions: Temporarily disable other extensions
  • Reduce test frequency: Avoid running tests too frequently
  • Clear extension data: Sign out and back in to reset state

Slow Test Execution​

Problem: Tests take much longer than expected

Solutions:

  • Check internet speed: Slow connection affects test performance
  • Verify server performance: Local server might be slow
  • Review test complexity: Complex tests naturally take longer
  • Check system load: Other processes might be consuming resources
  • Try simpler tests: Test basic functionality first

Platform-Specific Issues​

Next.js Development Server Issues​

Common Problems:

  • Port conflicts: Next.js default port 3000 conflicts with other services
  • Build vs Dev mode: Extension only works with npm run dev, not built apps
  • API routes not accessible: Check Next.js server configuration

Solutions:

  • Use npm run dev not npm start
  • Ensure API routes are working in development
  • Check next.config.js for custom configurations

React Development Issues​

Common Problems:

  • Create React App vs Vite: Different default ports (3000 vs 5173)
  • React StrictMode: Can cause double-rendering in development
  • Hot reloading conflicts: Fast refresh might interfere with testing

Solutions:

  • Configure correct port in extension settings
  • Tests account for React development behavior
  • Disable StrictMode if necessary for testing

Django Development Issues​

Common Problems:

  • Port confusion: Django default port 8000 vs frontend port 3000
  • ALLOWED_HOSTS: Django might reject requests from extension
  • Static files: CSS/JS might not load properly in development

Solutions:

  • Set extension port to 8000 for Django
  • Add localhost to ALLOWED_HOSTS
  • Run python manage.py runserver not production server

Network and Firewall Issues​

Corporate Firewall Blocking​

Problem: Extension can't connect due to firewall

Solutions:

  • Contact IT: Request whitelist for *.debugg.ai domains
  • Check proxy settings: Configure VS Code proxy settings if needed
  • Try different network: Test on personal network to confirm issue
  • Use VPN: Try connecting through VPN to bypass restrictions

VPN Interference​

Problem: VPN blocks localhost connections

Solutions:

  • Disable VPN: Temporarily disable for local testing
  • Configure VPN: Set VPN to allow localhost traffic
  • Use different DNS: Try different DNS servers
  • Split tunneling: Configure VPN to exclude localhost

Getting Help​

Before Contacting Support​

Gather this information:

  • Extension version: Found in Extensions panel
  • IDE version: VS Code/Cursor version number
  • Operating system: Windows/macOS/Linux and version
  • Error messages: Exact error text and screenshots
  • Console logs: Output from Output → DebuggAI
  • Steps to reproduce: What you did when the issue occurred

Community Support​

Direct Support​

  • Email: hello@debugg.ai
  • Response time: Usually within 24 hours
  • Include details: Provide all relevant information above
  • Priority support: Available for Pro and Team plan users

Emergency Issues​

For critical issues affecting production or blocking development:

  • Email: support@debugg.ai with "URGENT" in subject
  • Discord: Ping @support in the Discord channel
  • Include impact: Explain how the issue affects your work

Frequently Asked Questions​

Does DebuggAI Work Offline?​

Answer: No, DebuggAI requires internet connection to:

  • Authenticate with your account
  • Send test descriptions to AI processing
  • Receive test results and analysis
  • Download test scripts and recordings

Can I Test Production Applications?​

Answer: DebuggAI is designed for local development testing. For production testing:

  • Use traditional testing frameworks
  • Consider DebuggAI for pre-deployment validation
  • Contact us about enterprise solutions for production testing

How Much Data Does DebuggAI Collect?​

Answer: DebuggAI collects minimal data:

  • Test descriptions and results
  • Basic usage analytics
  • Error reports for debugging
  • No source code or sensitive data

Why Don't My Tests Work in Build Mode?​

Answer: DebuggAI tests against development servers because:

  • Development servers are more accessible
  • Built applications may have different configurations
  • Development mode provides better debugging information
  • Production builds are optimized differently

Can I Use DebuggAI with Multiple Projects?​

Answer: Yes, configure different projects with:

  • Separate workspace settings
  • Different port configurations
  • Project-specific test descriptions
  • Team-based access control

Still having issues? Join our Discord or contact support for personalized help.