gmakstutis/openrag
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request #701 from langflow-ai/docs-22-dec-25

Browse source 
Docs: Add some troubleshooting advice
This commit is contained in:
April I. Murphy 2025-12-22 14:19:38 -08:00 • committed by GitHub
commit a9156aec68
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 59 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
docs/docs/_partial-prereq-no-script.mdx
View file

@ -2,5 +2,9 @@
* Install [Podman](https://podman.io/docs/installation) (recommended) or [Docker](https://docs.docker.com/get-docker/).
The OpenRAG team recommends, at minimum, 8 GB of RAM for container VMs.
However, if you plan to upload large files regularly, more RAM is recommended.
For more information, see [Troubleshoot OpenRAG](/support/troubleshoot).
* Install [`podman-compose`](https://docs.podman.io/en/latest/markdown/podman-compose.1.html) or [Docker Compose](https://docs.docker.com/compose/install/).
To use Docker Compose with Podman, you must alias Docker Compose commands to Podman commands.

8
docs/docs/core-components/chat.mdx
View file

@ -100,3 +100,11 @@ To simplify this integration, you can get pre-configured code snippets directly
The following example demonstrates how to generate and use code snippets for the **OpenRAG OpenSearch Agent** flow:
<PartialIntegrateChat />
## Troubleshoot chat {#troubleshoot-chat}
The following issues can occur when using the OpenRAG **Chat** feature:
* Documents seem to be missing or interpreted incorrectly: See [Troubleshoot ingestion](/ingestion#troubleshoot-ingestion).
* Service is suddenly unavailable when it was working previously: If there is no other obvious cause, such as the service or container VM being stopped or disconnected, there might be a problem with the flow configuration. Use the [**Restore flow** option](/agents#revert-a-built-in-flow-to-its-original-configuration) to revert the **OpenRAG OpenSearch Agent** flow to its original configuration.
If you made customizations to the flow, make sure to [export your flow](https://docs.langflow.org/concepts-flows-import) before restoring the flow.

11
docs/docs/core-components/ingestion.mdx
View file

@ -236,11 +236,22 @@ All errors were file-specific, and they didn't stop the pipeline.
## Troubleshoot ingestion {#troubleshoot-ingestion}
The following issues can occur during document ingestion.
### Failed or slow ingestion
If an ingestion task fails, do the following:
* Make sure you are uploading supported file types.
* Split excessively large files into smaller files before uploading.
* Remove unusual embedded content, such as videos or animations, before uploading. Although Docling can replace some non-text content with placeholders during ingestion, some embedded content might cause errors.
* Make sure your Podman/Docker VM has sufficient memory for the ingestion tasks.
The minimum recommendation is 8 GB of RAM.
If you regularly upload large files, more RAM is recommended.
For more information, see [Memory issue with Podman on macOS](/support/troubleshoot#memory-issue-with-podman-on-macos) and [Container out of memory errors](/support/troubleshoot#container-out-of-memory-errors).
* If OCR ingestion fails due to OCR missing, see [OCR ingestion fails (easyocr not installed)](/support/troubleshoot#ocr-ingestion-fails-easyocr-not-installed).
### Problems when referencing documents in chat
If the OpenRAG **Chat** doesn't seem to use your documents correctly, [browse your knowledge base](/knowledge#browse-knowledge) to confirm that the documents are uploaded in full, and the chunks are correct.

10
docs/docs/get-started/manage-services.mdx
View file

@ -161,6 +161,16 @@ To reset your OpenRAG deployment _and_ delete all OpenRAG data, see [Reinstall O
</TabItem>
</Tabs>
## Prune images
Use image pruning to free up disk space by removing unused OpenRAG container images.
For TUI-managed services, use the TUI's **Prune Images** option to clean up your OpenRAG container images.
You can choose to prune unused images only or all images.
If you prune all images, the OpenRAG services are stopped, all images are pruned, and then the required images are pulled the next time you start the OpenRAG services.
For self-managed services, use [`docker image prune`](https://docs.docker.com/engine/reference/commandline/image_prune/) or [`podman image prune`](https://docs.podman.io/en/latest/markdown/podman-image-prune.1.html) to remove unused images.
## See also
* [Uninstall OpenRAG](/uninstall)

32
docs/docs/support/troubleshoot.mdx
View file

@ -7,13 +7,17 @@ import PartialOllamaModels from '@site/docs/_partial-ollama-models.mdx';
This page provides troubleshooting advice for issues you might encounter when using OpenRAG or contributing to OpenRAG.
## OpenSearch fails to start
## Installation and start up issues
The following issues relate to OpenRAG installation and start up.
### 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
### 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).
@ -21,7 +25,7 @@ The error occurs because OpenRAG is running within a WSL environment, so `webbro
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
### 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:
@ -31,19 +35,27 @@ open "/Applications/Python VERSION/Install Certificates.command"
Replace `VERSION` with your installed Python version, such as `3.13`.
### Application onboarding gets stuck on Google Chrome
If the OpenRAG onboarding process gets stuck when using Google Chrome, try clearing your browser's cache.
## 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
## Container out of memory errors {#container-out-of-memory-errors}
Increase Docker memory allocation or use the CPU-only deployment (base `docker-compose.yml` without GPU override) to reduce memory usage.
Increase your container VM's allocated memory, or use a CPU-only deployment to reduce memory usage.
## Memory issue with Podman on macOS
For TUI-managed deployments, you can enable **CPU mode** on the TUI's **Status** page.
For self-managed deployments, CPU-only deployments use the `docker-compose.yml` file that doesn't have GPU overrides.
## Memory issue with Podman on macOS {#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.
This example increases the machine size to 8 GB of RAM, which is the minimum recommended RAM for OpenRAG:
```bash
podman machine stop
@ -63,7 +75,7 @@ With the default [environment variable](/reference/configuration) values, OpenRA
* 8000: Docling API
* 9200: OpenSearch service
## OCR ingestion fails (easyocr not installed)
## OCR ingestion fails (easyocr not installed) {#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).
@ -144,3 +156,7 @@ See [Troubleshoot ingestion](/ingestion#troubleshoot-ingestion).
## Ollama model issues
<PartialOllamaModels />
## Chat issues
See [Troubleshoot chat](/chat#troubleshoot-chat).