Skip to main content

# Troubleshoot OpenRAG

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​

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.

## OpenRAG installation fails with unable to get local issuer certificate​

If you are installing OpenRAG on macOS, and the installation fails with `unable to get local issuer certificate`, run the following command, and then retry the installation:

    open "/Applications/Python VERSION/Install Certificates.command"

Replace `VERSION` with your installed Python version, such as `3.13`.

## Langflow connection issues​

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

## Container out of memory errors​

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

## Memory issue with Podman on macOS​

If you're using Podman on macOS, you might 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 can 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`.

## Upgrade fails due to Langflow container already exists​

If you encounter a `langflow container already exists` error when upgrading OpenRAG, this typically means you upgraded OpenRAG with `uv`, but you didn't remove or upgrade containers from a previous installation.

To resolve this issue, do the following:

First, try removing only the Langflow container, and then retry the upgrade in the OpenRAG TUI by clicking Status and then Upgrade.

- Podman
- Docker

1. Stop the Langflow container:

       podman stop langflow

2. Remove the Langflow container:

       podman rm langflow --force

1. Stop the Langflow container:

       docker stop langflow

2. Remove the Langflow container:

       docker rm langflow --force

If reinstalling the Langflow container doesn't resolve the issue, you must reset to a fresh installation by removing all OpenRAG containers and data. Then, you can retry the upgrade.

warning

This is a destructive operation that completely resets your OpenRAG containers and removes all OpenRAG data, including OpenSearch data, uploaded documents, and authentication details. Your `.env` file is preserved, so your configuration settings remain intact, but all other data is lost.

To reset your installation, stop your containers, and then completely remove them. After removing the containers, retry the upgrade in the OpenRAG TUI by clicking Status and then Upgrade.

- Podman
- Docker

1. Stop all running containers:

       podman stop --all

2. Remove all containers, including stopped containers:

       podman rm --all --force

3. Remove all images:

       podman rmi --all --force

4. Remove all volumes:

       podman volume prune --force

5. Remove all networks except the default network:

       podman network prune --force

6. Clean up any leftover data:

       podman system prune --all --force --volumes

1. Stop all running containers:

       docker stop $(docker ps -q)

2. Remove all containers, including stopped containers:

       docker rm --force $(docker ps -aq)

3. Remove all images:

       docker rmi --force $(docker images -q)

4. Remove all volumes:

       docker volume prune --force

5. Remove all networks except the default network:

       docker network prune --force

6. Clean up any leftover data:

       docker system prune --all --force --volumes