140 lines
No EOL
5 KiB
Text
140 lines
No EOL
5 KiB
Text
---
|
|
title: Troubleshoot OpenRAG
|
|
slug: /support/troubleshoot
|
|
---
|
|
|
|
This page provides troubleshooting advice for issues you might encounter when using OpenRAG or contributing to OpenRAG.
|
|
|
|
## OpenSearch fails to start
|
|
|
|
Check that the value of the `OPENSEARCH_PASSWORD` [environment variable](/reference/configuration) meets the [OpenSearch password complexity requirements](https://docs.opensearch.org/latest/security/configuration/demo-configuration/#setting-up-a-custom-admin-password).
|
|
|
|
If you need to change the password, you must [reset the OpenRAG services](/manage-services).
|
|
|
|
## 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 that the value of the `LANGFLOW_SUPERUSER` environment variable is correct.
|
|
For more information about this variable and how this variable controls Langflow access, see [Langflow settings](/reference/configuration#langflow-settings).
|
|
|
|
## 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
|
|
|
|
With the default [environment variable](/reference/configuration) values, OpenRAG requires the following ports to be available on the host machine:
|
|
|
|
* 3000: Langflow application
|
|
* 5001: Docling local ingestion service
|
|
* 5601: OpenSearch Dashboards
|
|
* 7860: Docling UI
|
|
* 8000: Docling API
|
|
* 9200: OpenSearch service
|
|
|
|
## OCR ingestion fails (easyocr not installed)
|
|
|
|
Docling ingestion can fail with an OCR-related error that mentions `easyocr` is missing.
|
|
This is likely due to a stale `uv` cache when you [install OpenRAG with `uvx`](/install-uvx).
|
|
|
|
When you invoke OpenRAG with `uvx openrag`, `uvx` creates a cached, ephemeral environment that doesn't modify your project.
|
|
The location and path of this cache depends on your operating system.
|
|
For example, on macOS, this is typically a user cache directory, such as `~/.cache/uv`.
|
|
|
|
This cache can become stale, producing errors like missing dependencies.
|
|
|
|
1. [Exit the TUI](/tui).
|
|
|
|
2. Clear the `uv` cache:
|
|
|
|
```bash
|
|
uv cache clean
|
|
```
|
|
|
|
To clear the OpenRAG cache only, run:
|
|
|
|
```bash
|
|
uv cache clean openrag
|
|
```
|
|
|
|
3. Invoke OpenRAG to restart the TUI:
|
|
|
|
```bash
|
|
uvx openrag
|
|
```
|
|
|
|
4. Click **Open App**, and then retry document ingestion.
|
|
|
|
If you install OpenRAG with `uv`, dependencies are synced directly from your `pyproject.toml` file.
|
|
This should automatically install `easyocr` because `easyocr` is included as a dependency in OpenRAG's `pyproject.toml`.
|
|
|
|
If you don't need OCR, you can disable OCR-based processing in your [ingestion settings](/knowledge#knowledge-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:
|
|
|
|
1. Remove only the Langflow container:
|
|
|
|
1. Stop the Langflow container:
|
|
|
|
```bash title="Docker"
|
|
docker stop langflow
|
|
```
|
|
|
|
```bash title="Podman"
|
|
podman stop langflow
|
|
```
|
|
|
|
2. Remove the Langflow container:
|
|
|
|
```bash title="Docker"
|
|
docker rm langflow --force
|
|
```
|
|
|
|
```bash title="Podman"
|
|
podman rm langflow --force
|
|
```
|
|
|
|
2. Retry the [upgrade](/upgrade).
|
|
|
|
3. If reinstalling the Langflow container doesn't resolve the issue, then you must [reset all containers](/manage-services) or [reinstall OpenRAG](/reinstall).
|
|
|
|
4. Retry the [upgrade](/upgrade).
|
|
|
|
If no updates are available after reinstalling OpenRAG, then you reinstalled at the latest version, and your deployment is up to date.
|
|
|
|
## Document ingestion or similarity search issues
|
|
|
|
See [Troubleshoot ingestion](/ingestion#troubleshoot-ingestion). |