Skip to main content

# Troubleshooting

This page provides troubleshooting advice for issues you might encounter when using OpenRAG or contributing to OpenRAG.

## OpenSearch fails to start​

Check that `OPENSEARCH_PASSWORD` set in Environment variables meets requirements. The password must contain at least 8 characters, and must contain at least one uppercase letter, one lowercase letter, one digit, and one special character that is strong.

## OpenRAG fails to start from the TUI with "Operation not supported" error​

This error occurs when starting OpenRAG with the TUI in WSL (Windows Subsystem for Linux).

The error occurs because OpenRAG is running within a WSL environment, so `webbrowser.open()` can't launch a browser automatically.

To access the OpenRAG application, open a web browser and enter `http://localhost:3000` in the address bar.

## Langflow connection issues​

Verify the `LANGFLOW_SUPERUSER` credentials set in Environment variables are correct.

## Memory errors​

### Container out of memory errors​

Increase Docker memory allocation or use docker-compose-cpu.yml to deploy OpenRAG.

### Podman on macOS memory issues​

If you're using Podman on macOS, you may need to increase VM memory on your Podman machine. This example increases the machine size to 8 GB of RAM, which should be sufficient to run OpenRAG.

    podman machine stop
    podman machine rm
    podman machine init --memory 8192   # 8 GB example
    podman machine start

## Port conflicts​

Ensure ports 3000, 7860, 8000, 9200, 5601 are available.

## OCR ingestion fails (easyocr not installed)​

If Docling ingestion fails with an OCR-related error and mentions `easyocr` is missing, this is likely due to a stale `uv` cache.

`easyocr` is already included as a dependency in OpenRAG's `pyproject.toml`. Project-managed installations using `uv sync` and `uv run` always sync dependencies directly from your `pyproject.toml`, so they should have `easyocr` installed.

If you're running OpenRAG with `uvx openrag`, `uvx` creates a cached, ephemeral environment that doesn't modify your project. This cache may become stale.

On macOS, this cache directory is typically a user cache directory such as `/Users/USER_NAME/.cache/uv`.

1. To clear the uv cache, run:

       uv cache clean

2. Start OpenRAG:

       uvx openrag

If you do not need OCR, you can disable OCR-based processing in your ingestion settings to avoid requiring `easyocr`.

## Langflow container already exists​

If you are running other versions of Langflow containers on your machine, you may encounter an issue where Docker or Podman thinks Langflow is already up.

Remove just the problem container, or clean up all containers and start fresh.

To reset your local containers and pull new images, do the following:

1. Stop your containers and completely remove them.

   - Podman
   - Docker

       # Stop all running containers
       podman stop --all

       # Remove all containers (including stopped ones)
       podman rm --all --force

       # Remove all images
       podman rmi --all --force

       # Remove all volumes
       podman volume prune --force

       # Remove all networks (except default)
       podman network prune --force

       # Clean up any leftover data
       podman system prune --all --force --volumes

       # Stop all running containers
       docker stop $(docker ps -q)

       # Remove all containers (including stopped ones)
       docker rm --force $(docker ps -aq)

       # Remove all images
       docker rmi --force $(docker images -q)

       # Remove all volumes
       docker volume prune --force

       # Remove all networks (except default)
       docker network prune --force

       # Clean up any leftover data
       docker system prune --all --force --volumes

2. Restart OpenRAG and upgrade to get the latest images for your containers.

       uv sync
       uv run openrag

3. In the OpenRAG TUI, click Status, and then click Upgrade. When the Close button is active, the upgrade is complete. Close the window and open the OpenRAG appplication.