> ## Documentation Index
> Fetch the complete documentation index at: https://docs.browserable.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

# 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:

```bash theme={null}
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:

```bash theme={null}
docker compose -f deployment.dev.yml exec tasks sh
pm2 logs
```

### 3. Restarting Backend Services

If you need to restart the backend services:

```bash theme={null}
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:
  ```bash theme={null}
  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](https://discord.gg/b6s9fXNjeQ) for real-time support
3. Report issues on our [GitHub repository](https://github.com/browserable/browserable)