---
title: Troubleshoot OpenRAG
slug: /support/troubleshoot
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

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](/reference/configuration) 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)](https://learn.microsoft.com/en-us/windows/wsl/install).

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:

```bash
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](/reference/configuration) are correct.

## Container out of memory errors

Increase Docker memory allocation or use [docker-compose-cpu.yml](https://github.com/langflow-ai/openrag/blob/main/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.

```bash
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:

   ```bash
   uv cache clean
   ```

2. Start OpenRAG:

   ```bash
   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 {#langflow-container-already-exists-during-upgrade}

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**.

<Tabs groupId="Container software">
<TabItem value="Podman" label="Podman">

1. Stop the Langflow container:

   ```bash
   podman stop langflow
   ```

2. Remove the Langflow container:

   ```bash
   podman rm langflow --force
   ```

</TabItem>
<TabItem value="Docker" label="Docker" default>

1. Stop the Langflow container:

   ```bash
   docker stop langflow
   ```

2. Remove the Langflow container:

   ```bash
   docker rm langflow --force
   ```

</TabItem>
</Tabs>

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**.

<Tabs groupId="Container software">
<TabItem value="Podman" label="Podman">

1. Stop all running containers:

   ```bash
   podman stop --all
   ```

2. Remove all containers, including stopped containers:

   ```bash
   podman rm --all --force
   ```

3. Remove all images:

   ```bash
   podman rmi --all --force
   ```

4. Remove all volumes:

   ```bash
   podman volume prune --force
   ```

5. Remove all networks except the default network:

   ```bash
   podman network prune --force
   ```

6. Clean up any leftover data:

   ```bash
   podman system prune --all --force --volumes
   ```

</TabItem>
<TabItem value="Docker" label="Docker" default>

1. Stop all running containers:

   ```bash
   docker stop $(docker ps -q)
   ```

2. Remove all containers, including stopped containers:

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

3. Remove all images:

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

4. Remove all volumes:

   ```bash
   docker volume prune --force
   ```

5. Remove all networks except the default network:

   ```bash
   docker network prune --force
   ```

6. Clean up any leftover data:

   ```bash
   docker system prune --all --force --volumes
   ```

</TabItem>
</Tabs>