Donobu Logo

Troubleshooting Donobu Studio

Solve common issues with Donobu Studio, including installation problems, GPT configuration errors, flow execution failures, and browser issues.

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

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), or Windows 10/11
  • At least 4GB RAM available
  • 2GB free disk space

2. Reset Application Data

macOS:

# Close Donobu completely
rm -rf ~/Library/Application\ Support/Donobu
rm -rf ~/Library/Caches/Donobu
# Restart Donobu

Windows:

# Close Donobu completely
# Remove application data
Remove-Item -Recurse -Force "$env:APPDATA\Donobu"
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\Donobu"
# Restart Donobu

3. Check Permissions

  • macOS: Grant Accessibility permissions in System Preferences > Privacy & Security. Restart after granting permissions.
  • Windows: Try running Donobu as Administrator. Check that your antivirus is not blocking the application.

API Server Not Responding

Symptoms:

  • "Connection refused" errors in Studio
  • Flows fail to start
  • Settings changes don't save

Solutions:

  1. Restart Studio — Close and reopen Donobu Studio. The API server starts automatically with the app.

  2. Check for port conflicts — The API server runs on port 31000. Ensure no other application is using this port:

    macOS/Linux:

    lsof -i :31000

    Windows (PowerShell):

    Get-NetTCPConnection -LocalPort 31000

  3. Verify the server is running:

    curl -X GET http://localhost:31000/api/ping
# Expected response: OK

GPT Configuration Issues

"GPT Config Not Found" Errors

Symptoms:

  • Flow fails with "GPT configuration not found"
  • Flows stuck in Initializing state

Solutions:

  1. Open Studio's Settings page and verify you have at least one LLM provider configured with a valid API key.
  2. Check that your API key is valid and has sufficient quota/credits with the provider.
  3. If using multiple providers, ensure the correct provider is selected for your flow.

<!-- [SCREENSHOT: Studio settings page showing the LLM provider configuration section] -->

API Rate Limiting

Symptoms:

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

Solutions:

  1. Wait a few minutes and retry — most rate limits reset quickly.
  2. Switch to a different LLM provider or model in Studio settings.
  3. If running many flows in parallel, reduce concurrency.

Flow Execution Problems

Flows Stuck in Initializing

Symptoms:

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

Solutions:

  1. Cancel the flow and try again with a simpler objective.
  2. Check that your LLM provider key is still valid (Settings page).
  3. Verify system resources — close other browser windows to free memory.
  4. Try running with a different browser device in the flow options.

Flows Failing with "Objective Not Completable"

Symptoms:

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

Solutions:

  1. Simplify the objective — Break complex goals into smaller, focused flows. Instead of "Find the best headphones, compare prices, add to cart, and checkout," try "Search for wireless headphones and navigate to the first product page."
  2. Increase the max tool calls — The flow may be running out of allowed steps before completing. Increase the limit in the flow options.
  3. Check the target website — Some sites have aggressive bot protection that blocks automation. Try a different site to confirm Studio is working correctly.

Element Not Found Errors

Symptoms:

  • Actions failing on dynamic content
  • "Timeout waiting for element" messages

Solutions:

  1. The target page may have changed since the flow was last run. If rerunning a flow, try creating a new flow instead.
  2. If the site uses heavy JavaScript rendering, the page may not be fully loaded when the AI tries to interact. Running the flow again often resolves this as the AI adapts.
  3. For sites behind authentication, ensure your browser state is correctly configured — see Using a Logged-In Browser State.

Browser & Network Issues

Page Load Timeouts

Symptoms:

  • "Navigation timeout" errors
  • Flows failing on slow pages

Solutions:

  1. Check your network connection.
  2. Try the flow again — transient network issues are common.
  3. If the target site is consistently slow, the AI will adapt, but you may need to increase the max tool calls to give it more time.

SSL/Certificate Issues

Symptoms:

  • HTTPS sites not loading
  • Certificate error messages

Solutions:

  1. For local development sites, use http://localhost:... instead of HTTPS.
  2. For external sites with certificate issues, verify the site loads correctly in a regular browser first.

Getting Help

When you need additional support:

  1. Gather information — Note the flow ID, error messages, and what you were trying to do.
  2. Check the results view — Open the flow in Studio to review screenshots and the step timeline for clues.
  3. Simplify and reproduce — Try to reproduce the issue with a simpler objective or on a public website.