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 encounter a langflow container already exists error when upgrading OpenRAG, this typically means you upgraded OpenRAG with uv, but didn't remove or upgrade containers from a previous installation.

  1. Remove only the problematic Langflow container:

    # Stop the langflow container
    docker stop langflow

    # Remove the langflow container
    docker rm langflow --force

  2. After removing the container, retry the upgrade in the OpenRAG TUI by clicking Status > Upgrade.

Reinstall all containers​

If reinstalling the Langflow container doesn't resolve the issue, or if you want a completely fresh installation, remove all OpenRAG containers and data, and then retry the upgrade.

Data loss

The complete reset removes all your data, including OpenSearch data, uploaded documents, and authentication. Your .env file is preserved, so your configuration settings remain intact.

  1. Stop your containers and completely remove them.

    # 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. After removing the containers, retry the upgrade in the OpenRAG TUI by clicking Status > Upgrade.