226 lines
No EOL
6.5 KiB
Text
226 lines
No EOL
6.5 KiB
Text
---
|
|
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 don't 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 destroys your OpenRAG containers and their contents.
|
|
However, your `.env` file (configuration settings) and `./opensearch-data` (OpenSearch knowledge base) are preserved.
|
|
:::
|
|
|
|
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>
|
|
|
|
## Reinstalling OpenRAG doesn't reset onboarding {#reinstalling-openrag-doesnt-reset-onboarding}
|
|
|
|
If you [reinstall OpenRAG](/install#reinstall), you can restore your installation to it's original, default state by resetting the containers _and_ deleting the `.env` file.
|
|
|
|
When you start OpenRAG after doing this, you should be prompted to go through the initial setup and onboarding process again.
|
|
|
|
Due to a known issue, the onboarding process might not reset when you reinstall OpenRAG.
|
|
If this occurs, [install OpenRAG in a new Python project directory](/install#install) (with `uv init` and `uv add openrag`).
|
|
|
|
## Document ingestion or similarity search issues
|
|
|
|
See [Troubleshoot ingestion](/ingestion#troubleshoot-ingestion). |