Troubleshooting Guide

Common Issues & Solutions 🔧

This guide helps you quickly identify and resolve common problems with Donobu automation flows.

Installation & Setup Issues

Donobu Won't Start

Symptoms:

• App crashes on startup
• "Failed to initialize" error messages
• Blank window or loading screen

Solutions:

1. Check System Requirements

   • macOS 10.15 or later (Intel/Apple Silicon)
   • At least 4GB RAM available
   • 2GB free disk space

2. Reset Application Data

   # Close Donobu completely
   # Remove application data (macOS)
   rm -rf ~/Library/Application\ Support/Donobu
   rm -rf ~/Library/Caches/Donobu
   
   # Restart Donobu
   

3. Check Permissions

   • Grant Accessibility permissions in System Preferences
   • Allow Donobu in Privacy & Security settings
   • Restart after granting permissions

API Server Not Responding

Symptoms:

• curl: (7) Failed to connect to localhost port 31000
• "Connection refused" errors
• API endpoints returning 404

Solutions:

1. Verify Server Status

   # Check if API server is running
   curl -X GET http://localhost:31000/api/ping
   
   # Expected response: {"status": "pong"}
   

2. Restart API Server

   • Close and reopen Donobu Studio
   • Check "API Server" status in app settings
   • Verify no other applications are using port 31000

3. Port Conflicts

   # Check what's using port 31000
   lsof -i :31000
   
   # Kill conflicting processes if necessary
   kill -9 <PID>
   

GPT Configuration Issues

"GPT Config Not Found" Errors

Symptoms:

• Flow fails with "GPT configuration 'xyz' not found"
• "No valid GPT configuration" messages
• Flows stuck in INITIALIZING state

Solutions:

1. List Current Configurations

   curl -X GET http://localhost:31000/api/gpt-configs
   

2. Create Missing Configuration

   # OpenAI example
   curl -X POST http://localhost:31000/api/gpt-configs/openai-gpt4 \
     -H "Content-Type: application/json" \
     -d '{
       "type": "OPENAI",
       "apiKey": "your-api-key",
       "modelName": "gpt-4"
     }'
   

3. Verify API Key Validity

   • Test API key directly with provider
   • Check for expired or invalid credentials
   • Ensure sufficient API quota/credits

API Rate Limiting

Symptoms:

• "Rate limit exceeded" errors
• Flows failing after partial completion
• Slow response times from GPT

Solutions:

1. Implement Delays

   {
     "customTools": [{
       "name": "rateLimitedRequest",
       "description": "Makes request with rate limiting",
       "javascript": `
         // Add delay between AI requests
         await page.waitForTimeout(2000);
         // Continue with normal flow
       `
     }]
   }
   

2. Use Different Model

   • Switch to less restrictive model
   • Use multiple API keys/configurations
   • Distribute load across different providers

Flow Execution Problems

Flows Stuck in INITIALIZING

Symptoms:

• Flow state remains "INITIALIZING"
• Browser window never opens
• No progress after several minutes

Debugging Steps:

1. Check Browser Configuration

   {
     "browser": {
       "using": {
         "type": "device",
         "deviceName": "Desktop Chromium",  // Verify valid device name
         "headless": false  // Try with headless=false first
       }
     }
   }
   

2. Verify System Resources

   # Check available memory
   vm_stat
   
   # Check CPU usage
   top -n 1
   

3. Test Simple Flow

   {
     "name": "Debug Test",
     "targetWebsite": "https://example.com",
     "overallObjective": "Just navigate to the page",
     "maxToolCalls": 1
   }
   

Element Not Found Errors

Symptoms:

• "Element not found" or "Selector not found"
• "Timeout waiting for selector"
• Actions failing on dynamic content

Solutions:

1. Add Wait Conditions

   {
     "customTools": [{
       "name": "waitForElement",
       "description": "Wait for element to be available",
       "inputSchema": {
         "type": "object",
         "properties": {
           "selector": {"type": "string"},
           "timeout": {"type": "number", "default": 10000}
         }
       },
       "javascript": `
         await page.locator(selector).waitFor({
           state: 'visible',
           timeout: timeout
         });
       `
     }]
   }
   

2. Use More Resilient Selectors

   // Bad - fragile selectors
   "#button-123"
   ".container > div:nth-child(3)"
   
   // Good - semantic selectors  
   "[data-testid='submit-button']"
   "button:has-text('Submit')"
   "[aria-label='Close dialog']"
   

3. Handle Dynamic Content

   {
     "customTools": [{
       "name": "handleDynamicContent",
       "description": "Waits for dynamic content to stabilize",
       "javascript": `
         // Wait for network to be idle
         await page.waitForLoadState('networkidle');
         
         // Wait for specific content to load
         await page.waitForFunction(() => {
           return document.querySelectorAll('.dynamic-item').length > 0;
         });
       `
     }]
   }
   

Flows Failing with "Objective Not Completable"

Symptoms:

• Flow reaches "FAILED" state
• AI reports "Cannot complete objective"
• Partial completion with early termination

Debugging Approaches:

1. Simplify Objective

   // Instead of complex objective
   {
     "overallObjective": "Find the best wireless headphones under $100, compare prices across multiple vendors, add to cart, and proceed to checkout"
   }
   
   // Break into smaller parts
   {
     "overallObjective": "Search for wireless headphones and navigate to the first product page"
   }
   

2. Add Intermediate Validation

   {
     "resultJsonSchema": {
       "type": "object",
       "properties": {
         "searchCompleted": {"type": "boolean"},
         "productFound": {"type": "boolean"},
         "priceExtracted": {"type": "boolean"}
       }
     }
   }
   

3. Enable Debug Mode

   {
     "browser": {
       "using": {
         "type": "device", 
         "headless": false  // Watch execution
       }
     },
     "isControlPanelEnabled": true  // Enable in-browser controls
   }
   

Browser & Network Issues

Page Load Timeouts

Symptoms:

• "Navigation timeout" errors
• Flows failing on slow pages
• Incomplete page renders

Solutions:

1. Increase Timeout Values

   {
     "customTools": [{
       "name": "navigateWithTimeout",
       "description": "Navigate with extended timeout",
       "inputSchema": {
         "type": "object",
         "properties": {
           "url": {"type": "string"},
           "timeout": {"type": "number", "default": 30000}
         }
       },
       "javascript": `
         await page.goto(url, {
           waitUntil: 'networkidle',
           timeout: timeout
         });
       `
     }]
   }
   

2. Handle Slow Networks

   {
     "browser": {
       "using": {
         "type": "device",
         "proxy": {
           "server": "http://your-proxy:8080"  // If behind corporate proxy
         }
       }
     }
   }
   

SSL/Certificate Issues

Symptoms:

• "Certificate error" messages
• HTTPS sites not loading
• "NET::ERR_CERT_INVALID" errors

Solutions:

1. Ignore Certificate Errors (Development Only)

   {
     "customTools": [{
       "name": "ignoreSSLErrors",
       "description": "Configure browser to ignore SSL errors", 
       "javascript": `
         // Note: Only use in development/testing environments
         await page.context().grantPermissions(['clipboard-read', 'clipboard-write']);
       `
     }]
   }
   

2. Use HTTP for Local Testing

   {
     "targetWebsite": "http://localhost:3000"  // Use HTTP for local dev
   }
   

Performance Issues

Slow Flow Execution

Symptoms:

• Flows taking much longer than expected
• Browser appears frozen
• High CPU/memory usage

Optimization Strategies:

1. Reduce Visual Overhead

   {
     "browser": {
       "using": {
         "type": "device",
         "headless": true  // Faster execution
       }
     }
   }
   

2. Optimize Tool Selection

   {
     "allowedTools": [
       "click", "type", "goToWebpage", "assert"  // Only essential tools
     ]
   }
   

3. Disable Unnecessary Features

   {
     "isControlPanelEnabled": false,  // Disable UI controls
     "defaultMessageDuration": 0      // Skip AI messages
   }
   

Memory Leaks

Symptoms:

• Increasing memory usage over time
• Browser crashes during long flows
• System becoming unresponsive

Solutions:

1. Clean Up Resources

   {
     "customTools": [{
       "name": "cleanupResources",
       "description": "Clean up browser resources",
       "javascript": `
         // Close unused tabs
         const pages = page.context().pages();
         for (let i = 1; i < pages.length; i++) {
           await pages[i].close();
         }
         
         // Clear browser data periodically
         await page.context().clearCookies();
       `
     }]
   }
   

2. Limit Flow Duration

   {
     "maxToolCalls": 50,  // Prevent runaway flows
     "callbackUrl": "https://your-app.com/cleanup"  // Cleanup webhook
   }
   

Debugging Techniques 🔍

Enable Comprehensive Logging

1. Flow Debugging

   # Get detailed flow information
   curl -X GET http://localhost:31000/api/flows/{flowId}
   
   # Get all tool calls
   curl -X GET http://localhost:31000/api/flows/{flowId}/tool-calls
   

2. Visual Debugging

   # Download screenshots at each step
   curl -X GET http://localhost:31000/api/flows/{flowId}/images/{imageId} \
     --output debug-step-{imageId}.png
   
   # Download full video
   curl -X GET http://localhost:31000/api/flows/{flowId}/video \
     --output debug-flow.webm
   

Custom Debugging Tools

{
  "customTools": [{
    "name": "debugPageState",
    "description": "Captures comprehensive page state for debugging",
    "javascript": `
      const state = {
        url: page.url(),
        title: await page.title(),
        viewport: await page.viewportSize(),
        elements: await page.evaluate(() => {
          return Array.from(document.querySelectorAll('*')).length;
        }),
        forms: await page.evaluate(() => {
          return Array.from(document.forms).map(f => ({
            action: f.action,
            method: f.method,
            elements: f.elements.length
          }));
        }),
        errors: await page.evaluate(() => {
          return window.console?.errors || [];
        })
      };
      
      console.log('DEBUG STATE:', JSON.stringify(state, null, 2));
      return state;
    `
  }]
}

Getting Help 💬

When you need additional support:

1. Gather Information

   • Flow ID and configuration
   • Error messages and stack traces
   • Screenshots/videos of the issue
   • System information (OS, browser version)

2. Create Minimal Reproduction

   • Simplify flow to minimal failing case
   • Remove sensitive data
   • Test with public websites when possible

3. Check Resources

   • Review API documentation
   • Search existing issues
   • Check system requirements

Remember: Most issues have simple solutions. Start with the basics (restart, check configurations, simplify objectives) before diving into complex debugging.