From 7417e300045444d51907d02dadeb45e23560de09 Mon Sep 17 00:00:00 2001 From: April M <36110273+aimurphy@users.noreply.github.com> Date: Mon, 22 Dec 2025 13:07:43 -0800 Subject: [PATCH] chat service stops working --- docs/docs/_partial-prereq-no-script.mdx | 1 + docs/docs/core-components/chat.mdx | 10 ++++++++- docs/docs/core-components/ingestion.mdx | 2 ++ docs/docs/support/troubleshoot.mdx | 30 +++++++++++++++++-------- 4 files changed, 33 insertions(+), 10 deletions(-) diff --git a/docs/docs/_partial-prereq-no-script.mdx b/docs/docs/_partial-prereq-no-script.mdx index c51f539d..d96c7ccc 100644 --- a/docs/docs/_partial-prereq-no-script.mdx +++ b/docs/docs/_partial-prereq-no-script.mdx @@ -4,6 +4,7 @@ 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 1ddb0387..3dfec56a 100644 --- a/docs/docs/core-components/ingestion.mdx +++ b/docs/docs/core-components/ingestion.mdx @@ -248,6 +248,8 @@ If an ingestion task fails, do the following: * 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 diff --git a/docs/docs/support/troubleshoot.mdx b/docs/docs/support/troubleshoot.mdx index 24a7d71e..51182e9b 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: @@ -36,14 +40,18 @@ Replace `VERSION` with your installed Python version, such as `3.13`. 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 +71,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 +151,8 @@ See [Troubleshoot ingestion](/ingestion#troubleshoot-ingestion). ## Ollama model issues - \ No newline at end of file + + +## Chat issues + +See [Troubleshoot chat](/core-components/chat#troubleshoot-chat). \ No newline at end of file