​
Troubleshooting Guide

This guide will help you diagnose and fix common issues you might encounter while using Browserable.

​
Basic Health Checks

​
1. Checking Service Health

To verify if all services are running properly: 
docker ps
This will show you the status of all containers. Make sure all services (ui, tasks, mongodb, redis, etc.) are in the “Healthy” state.

​
2. Checking Backend Logs

To check if the backend is running or if there are any errors: 
docker compose -f deployment.dev.yml exec tasks sh
pm2 logs

​
3. Restarting Backend Services

If you need to restart the backend services: 
docker exec -it tasks sh
pm2 restart all
pm2 logs
To exit from the container shell:
  • Press Ctrl + C

​
Common Issues and Solutions

​
1. URL Access Issues

  • Problem: 127.0.0.1 not working
  • Solution: Use localhost instead of 127.0.0.1 for all URLs
  • Explanation: Some services and configurations are specifically bound to localhost

​
2. Initial Setup Screen Issues

  • Problem: Stuck at “initial setup” screen
  • Solution: This typically indicates a backend connectivity issue
  • Troubleshooting Steps:
    1. Check backend logs using the commands above
    2. Verify all services are running with docker ps
    3. Check if the tasks service is healthy at http://localhost:2003/health

​
3. Rate Limit Errors

  • Problem: Getting 403 or 429 errors
  • Cause: API rate limits being exceeded
  • Solution:
    1. Consider using Gemini API keys for better rate limits and latency
    2. Check your current API usage in the settings panel
    3. If using OpenAI, consider upgrading your API tier

​
4. Browser Performance Issues

  • Problem: Remote browser is slow or unresponsive
  • Solution: Consider using the local browser setup
  • Steps:
    1. Follow the local browser setup guide in the documentation
    2. Start the local browser service:
    cd browser
npm install
npm start

​
Common Setup Mistakes

  1. URL Configuration
    • Always use localhost instead of 127.0.0.1 for all URLs
    • Ensure you’re using the correct ports as specified in the configuration
  2. Environment Variables
    • Make sure all required environment variables are set in your deployment.dev.yml OR in Admin UI -> API Keys
    • Check if API keys are properly configured in the settings
  3. Port Conflicts
    • Ensure no other services are using the required ports:
      • UI Server: 2001
      • Documentation: 2002
      • Tasks Server: 2003
      • MongoDB: 27017
      • Redis: 6379
      • MinIO: 9000, 9001
  4. Docker Issues
    • If containers fail to start:
      1. Stop all containers: docker compose -f deployment.dev.yml down
      2. Remove all containers: docker compose -f deployment.dev.yml down -v
      3. Rebuild and start: docker compose -f deployment.dev.yml up --build

​
Getting Help

If you’re still experiencing issues:
  1. Check the complete logs of the problematic service
  2. Join our Discord community for real-time support
  3. Report issues on our GitHub repository