diff --git a/docs/docs/_partial-prereq-no-script.mdx b/docs/docs/_partial-prereq-no-script.mdx
index a8fd8349..d96c7ccc 100644
--- a/docs/docs/_partial-prereq-no-script.mdx
+++ b/docs/docs/_partial-prereq-no-script.mdx
@@ -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.
\ No newline at end of file
diff --git a/docs/docs/core-components/chat.mdx b/docs/docs/core-components/chat.mdx
index 141e34c7..06fe60f1 100644
--- a/docs/docs/core-components/chat.mdx
+++ b/docs/docs/core-components/chat.mdx
@@ -99,4 +99,12 @@ 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:
-
\ No newline at end of file
+
+
+## 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.
\ No newline at end of file
diff --git a/docs/docs/core-components/ingestion.mdx b/docs/docs/core-components/ingestion.mdx
index 119a4b80..3dfec56a 100644
--- a/docs/docs/core-components/ingestion.mdx
+++ b/docs/docs/core-components/ingestion.mdx
@@ -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.
diff --git a/docs/docs/get-started/manage-services.mdx b/docs/docs/get-started/manage-services.mdx
index 69bda93a..98f15a6e 100644
--- a/docs/docs/get-started/manage-services.mdx
+++ b/docs/docs/get-started/manage-services.mdx
@@ -161,6 +161,16 @@ To reset your OpenRAG deployment _and_ delete all OpenRAG data, see [Reinstall O
+## 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)
\ No newline at end of file
diff --git a/docs/docs/support/troubleshoot.mdx b/docs/docs/support/troubleshoot.mdx
index 24a7d71e..f4d69e6e 100644
--- a/docs/docs/support/troubleshoot.mdx
+++ b/docs/docs/support/troubleshoot.mdx
@@ -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).
@@ -143,4 +155,8 @@ See [Troubleshoot ingestion](/ingestion#troubleshoot-ingestion).
## Ollama model issues
-
\ No newline at end of file
+
+
+## Chat issues
+
+See [Troubleshoot chat](/chat#troubleshoot-chat).
\ No newline at end of file