​

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