131 lines
No EOL
32 KiB
HTML
131 lines
No EOL
32 KiB
HTML
<!doctype html>
|
||
<html lang="en" dir="ltr" class="docs-wrapper plugin-docs plugin-id-default docs-version-current docs-doc-page docs-doc-id-support/troubleshoot" data-has-hydrated="false">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="generator" content="Docusaurus v3.9.2">
|
||
<title data-rh="true">Troubleshoot OpenRAG | OpenRAG</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" name="robots" content="noindex, nofollow"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:url" content="https://docs.openr.ag/support/troubleshoot"><meta data-rh="true" property="og:locale" content="en"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="docusaurus_version" content="current"><meta data-rh="true" name="docusaurus_tag" content="docs-default-current"><meta data-rh="true" name="docsearch:version" content="current"><meta data-rh="true" name="docsearch:docusaurus_tag" content="docs-default-current"><meta data-rh="true" property="og:title" content="Troubleshoot OpenRAG | OpenRAG"><meta data-rh="true" name="description" content="This page provides troubleshooting advice for issues you might encounter when using OpenRAG or contributing to OpenRAG."><meta data-rh="true" property="og:description" content="This page provides troubleshooting advice for issues you might encounter when using OpenRAG or contributing to OpenRAG."><link data-rh="true" rel="icon" href="/img/favicon.ico"><link data-rh="true" rel="canonical" href="https://docs.openr.ag/support/troubleshoot"><link data-rh="true" rel="alternate" href="https://docs.openr.ag/support/troubleshoot" hreflang="en"><link data-rh="true" rel="alternate" href="https://docs.openr.ag/support/troubleshoot" hreflang="x-default"><script data-rh="true" type="application/ld+json">{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Troubleshoot OpenRAG","item":"https://docs.openr.ag/support/troubleshoot"}]}</script><link rel="stylesheet" href="/assets/css/styles.66669ecc.css">
|
||
<script src="/assets/js/runtime~main.03e752b6.js" defer="defer"></script>
|
||
<script src="/assets/js/main.bf3320e5.js" defer="defer"></script>
|
||
</head>
|
||
<body class="navigation-with-keyboard">
|
||
<svg style="display: none;"><defs>
|
||
<symbol id="theme-svg-external-link" viewBox="0 0 24 24"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"/></symbol>
|
||
</defs></svg>
|
||
<script>!function(){var t=function(){try{return new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}}()||function(){try{return window.localStorage.getItem("theme")}catch(t){}}();document.documentElement.setAttribute("data-theme",t||"light"),document.documentElement.setAttribute("data-theme-choice",t||"light")}(),function(){try{const c=new URLSearchParams(window.location.search).entries();for(var[t,e]of c)if(t.startsWith("docusaurus-data-")){var a=t.replace("docusaurus-data-","data-");document.documentElement.setAttribute(a,e)}}catch(t){}}()</script><div id="__docusaurus"><link rel="preload" as="image" href="/img/logo-openrag-light.svg"><link rel="preload" as="image" href="/img/logo-openrag-dark.svg"><div role="region" aria-label="Skip to main content"><a class="skipToContent_fXgn" href="#__docusaurus_skipToContent_fallback">Skip to main content</a></div><nav aria-label="Main" class="theme-layout-navbar navbar navbar--fixed-top"><div class="navbar__inner"><div class="theme-layout-navbar-left navbar__items"><button aria-label="Toggle navigation bar" aria-expanded="false" class="navbar__toggle clean-btn" type="button"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a class="navbar__brand" href="/"><div class="navbar__logo"><img src="/img/logo-openrag-light.svg" alt="OpenRAG Logo" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/img/logo-openrag-dark.svg" alt="OpenRAG Logo" class="themedComponent_mlkZ themedComponent--dark_xIcU"></div></a></div><div class="theme-layout-navbar-right navbar__items navbar__items--right"><a href="https://github.com/langflow-ai/openrag" target="_blank" class="navbar__item navbar__link header-github-link" aria-label="GitHub repository"></a><div class="toggle_vylO colorModeToggle_DEke"><button class="clean-btn toggleButton_gllP toggleButtonDisabled_aARS" type="button" disabled="" title="system mode" aria-label="Switch between dark and light mode (currently system mode)"><svg viewBox="0 0 24 24" width="24" height="24" aria-hidden="true" class="toggleIcon_g3eP lightToggleIcon_pyhR"><path fill="currentColor" d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"></path></svg><svg viewBox="0 0 24 24" width="24" height="24" aria-hidden="true" class="toggleIcon_g3eP darkToggleIcon_wfgR"><path fill="currentColor" d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"></path></svg><svg viewBox="0 0 24 24" width="24" height="24" aria-hidden="true" class="toggleIcon_g3eP systemToggleIcon_QzmC"><path fill="currentColor" d="m12 21c4.971 0 9-4.029 9-9s-4.029-9-9-9-9 4.029-9 9 4.029 9 9 9zm4.95-13.95c1.313 1.313 2.05 3.093 2.05 4.95s-0.738 3.637-2.05 4.95c-1.313 1.313-3.093 2.05-4.95 2.05v-14c1.857 0 3.637 0.737 4.95 2.05z"></path></svg></button></div><div class="navbarSearchContainer_Bca1"></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div id="__docusaurus_skipToContent_fallback" class="theme-layout-main main-wrapper mainWrapper_z2l0"><div class="docsWrapper_hBAB"><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_sjWU" type="button"></button><div class="docRoot_UBD9"><aside class="theme-doc-sidebar-container docSidebarContainer_YfHR"><div class="sidebarViewport_aRkj"><div class="sidebar_njMd"><nav aria-label="Docs sidebar" class="menu thin-scrollbar menu_SIkG"><ul class="theme-doc-sidebar-menu menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/"><span title="About OpenRAG" class="linkLabel_WmDU">About OpenRAG</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/quickstart"><span title="Quickstart" class="linkLabel_WmDU">Quickstart</span></a></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret" role="button" aria-expanded="false" href="/install-options"><span title="Installation" class="categoryLinkLabel_W154">Installation</span></a></div></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/tui"><span title="Use the TUI" class="linkLabel_WmDU">Use the TUI</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/manage-services"><span title="Manage services" class="linkLabel_WmDU">Manage services</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/agents"><span title="Flows" class="linkLabel_WmDU">Flows</span></a></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret" role="button" aria-expanded="false" href="/knowledge"><span title="Knowledge" class="categoryLinkLabel_W154">Knowledge</span></a></div></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/chat"><span title="Chat" class="linkLabel_WmDU">Chat</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/reference/configuration"><span title="Environment variables" class="linkLabel_WmDU">Environment variables</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/support/contribute"><span title="Contribute to OpenRAG" class="linkLabel_WmDU">Contribute to OpenRAG</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link menu__link--active" aria-current="page" href="/support/troubleshoot"><span title="Troubleshoot OpenRAG" class="linkLabel_WmDU">Troubleshoot OpenRAG</span></a></li></ul></nav></div></div></aside><main class="docMainContainer_TBSr"><div class="container padding-top--md padding-bottom--lg"><div class="row"><div class="col docItemCol_VOVn"><div class="docItemContainer_Djhp"><article><nav class="theme-doc-breadcrumbs breadcrumbsContainer_Z_bl" aria-label="Breadcrumbs"><ul class="breadcrumbs"><li class="breadcrumbs__item"><a aria-label="Home page" class="breadcrumbs__link" href="/"><svg viewBox="0 0 24 24" class="breadcrumbHomeIcon_YNFT"><path d="M10 19v-5h4v5c0 .55.45 1 1 1h3c.55 0 1-.45 1-1v-7h1.7c.46 0 .68-.57.33-.87L12.67 3.6c-.38-.34-.96-.34-1.34 0l-8.36 7.53c-.34.3-.13.87.33.87H5v7c0 .55.45 1 1 1h3c.55 0 1-.45 1-1z" fill="currentColor"></path></svg></a></li><li class="breadcrumbs__item breadcrumbs__item--active"><span class="breadcrumbs__link">Troubleshoot OpenRAG</span></li></ul></nav><div class="tocCollapsible_ETCw theme-doc-toc-mobile tocMobile_ITEo"><button type="button" class="clean-btn tocCollapsibleButton_TO0P">On this page</button></div><div class="theme-doc-markdown markdown"><header><h1>Troubleshoot OpenRAG</h1></header><p>This page provides troubleshooting advice for issues you might encounter when using OpenRAG or contributing to OpenRAG.</p>
|
||
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="installation-and-start-up-issues">Installation and start up issues<a href="#installation-and-start-up-issues" class="hash-link" aria-label="Direct link to Installation and start up issues" title="Direct link to Installation and start up issues" translate="no"></a></h2>
|
||
<p>The following issues relate to OpenRAG installation and start up.</p>
|
||
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="opensearch-fails-to-start">OpenSearch fails to start<a href="#opensearch-fails-to-start" class="hash-link" aria-label="Direct link to OpenSearch fails to start" title="Direct link to OpenSearch fails to start" translate="no"></a></h3>
|
||
<p>Check that the value of the <code>OPENSEARCH_PASSWORD</code> <a class="" href="/reference/configuration">environment variable</a> meets the <a href="https://docs.opensearch.org/latest/security/configuration/demo-configuration/#setting-up-a-custom-admin-password" target="_blank" rel="noopener noreferrer" class="">OpenSearch password complexity requirements</a>.</p>
|
||
<p>If you need to change the password, you must <a class="" href="/manage-services">reset the OpenRAG services</a>.</p>
|
||
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="openrag-fails-to-start-from-the-tui-with-operation-not-supported">OpenRAG fails to start from the TUI with operation not supported<a href="#openrag-fails-to-start-from-the-tui-with-operation-not-supported" class="hash-link" aria-label="Direct link to OpenRAG fails to start from the TUI with operation not supported" title="Direct link to OpenRAG fails to start from the TUI with operation not supported" translate="no"></a></h3>
|
||
<p>This error occurs when starting OpenRAG with the TUI in <a href="https://learn.microsoft.com/en-us/windows/wsl/install" target="_blank" rel="noopener noreferrer" class="">WSL (Windows Subsystem for Linux)</a>.</p>
|
||
<p>The error occurs because OpenRAG is running within a WSL environment, so <code>webbrowser.open()</code> can't launch a browser automatically.</p>
|
||
<p>To access the OpenRAG application, open a web browser and enter <code>http://localhost:3000</code> in the address bar.</p>
|
||
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="openrag-installation-fails-with-unable-to-get-local-issuer-certificate">OpenRAG installation fails with unable to get local issuer certificate<a href="#openrag-installation-fails-with-unable-to-get-local-issuer-certificate" class="hash-link" aria-label="Direct link to OpenRAG installation fails with unable to get local issuer certificate" title="Direct link to OpenRAG installation fails with unable to get local issuer certificate" translate="no"></a></h3>
|
||
<p>If you are installing OpenRAG on macOS, and the installation fails with <code>unable to get local issuer certificate</code>, run the following command, and then retry the installation:</p>
|
||
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">open</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"/Applications/Python VERSION/Install Certificates.command"</span><br></span></code></pre></div></div>
|
||
<p>Replace <code>VERSION</code> with your installed Python version, such as <code>3.13</code>.</p>
|
||
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="application-onboarding-gets-stuck-on-google-chrome">Application onboarding gets stuck on Google Chrome<a href="#application-onboarding-gets-stuck-on-google-chrome" class="hash-link" aria-label="Direct link to Application onboarding gets stuck on Google Chrome" title="Direct link to Application onboarding gets stuck on Google Chrome" translate="no"></a></h3>
|
||
<p>If the OpenRAG onboarding process gets stuck when using Google Chrome, try clearing your browser's cache.</p>
|
||
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="langflow-connection-issues">Langflow connection issues<a href="#langflow-connection-issues" class="hash-link" aria-label="Direct link to Langflow connection issues" title="Direct link to Langflow connection issues" translate="no"></a></h2>
|
||
<p>Verify that the value of the <code>LANGFLOW_SUPERUSER</code> environment variable is correct.
|
||
For more information about this variable and how this variable controls Langflow access, see <a class="" href="/reference/configuration#langflow-settings">Langflow settings</a>.</p>
|
||
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="container-out-of-memory-errors">Container out of memory errors<a href="#container-out-of-memory-errors" class="hash-link" aria-label="Direct link to Container out of memory errors" title="Direct link to Container out of memory errors" translate="no"></a></h2>
|
||
<p>Increase your container VM's allocated memory, or use a CPU-only deployment to reduce memory usage.</p>
|
||
<p>For TUI-managed deployments, you can enable <strong>CPU mode</strong> on the TUI's <strong>Status</strong> page.</p>
|
||
<p>For self-managed deployments, CPU-only deployments use the <code>docker-compose.yml</code> file that doesn't have GPU overrides.</p>
|
||
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="memory-issue-with-podman-on-macos">Memory issue with Podman on macOS<a href="#memory-issue-with-podman-on-macos" class="hash-link" aria-label="Direct link to Memory issue with Podman on macOS" title="Direct link to Memory issue with Podman on macOS" translate="no"></a></h2>
|
||
<p>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 is the minimum recommended RAM for OpenRAG:</p>
|
||
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">podman</span><span class="token plain"> machine stop</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token function" style="color:#d73a49">podman</span><span class="token plain"> machine </span><span class="token function" style="color:#d73a49">rm</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token function" style="color:#d73a49">podman</span><span class="token plain"> machine init </span><span class="token parameter variable" style="color:#36acaa">--memory</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">8192</span><span class="token plain"> </span><span class="token comment" style="color:#999988;font-style:italic"># 8 GB example</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token function" style="color:#d73a49">podman</span><span class="token plain"> machine start</span><br></span></code></pre></div></div>
|
||
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="port-conflicts">Port conflicts<a href="#port-conflicts" class="hash-link" aria-label="Direct link to Port conflicts" title="Direct link to Port conflicts" translate="no"></a></h2>
|
||
<p>With the default <a class="" href="/reference/configuration">environment variable</a> values, OpenRAG requires the following ports to be available on the host machine:</p>
|
||
<ul>
|
||
<li class="">3000: Langflow application</li>
|
||
<li class="">5001: Docling local ingestion service</li>
|
||
<li class="">5601: OpenSearch Dashboards</li>
|
||
<li class="">7860: Docling UI</li>
|
||
<li class="">8000: Docling API</li>
|
||
<li class="">9200: OpenSearch service</li>
|
||
</ul>
|
||
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="ocr-ingestion-fails-easyocr-not-installed">OCR ingestion fails (easyocr not installed)<a href="#ocr-ingestion-fails-easyocr-not-installed" class="hash-link" aria-label="Direct link to OCR ingestion fails (easyocr not installed)" title="Direct link to OCR ingestion fails (easyocr not installed)" translate="no"></a></h2>
|
||
<p>Docling ingestion can fail with an OCR-related error that mentions <code>easyocr</code> is missing.
|
||
This is likely due to a stale <code>uv</code> cache when you <a class="" href="/install-uvx">install OpenRAG with <code>uvx</code></a>.</p>
|
||
<p>When you invoke OpenRAG with <code>uvx openrag</code>, <code>uvx</code> 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 <code>~/.cache/uv</code>.</p>
|
||
<p>This cache can become stale, producing errors like missing dependencies.</p>
|
||
<ol>
|
||
<li class="">
|
||
<p>If the TUI is open, press <kbd>q</kbd> to exit the TUI.</p>
|
||
</li>
|
||
<li class="">
|
||
<p>Clear the <code>uv</code> cache:</p>
|
||
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token plain">uv cache clean</span><br></span></code></pre></div></div>
|
||
<p>To clear the OpenRAG cache only, run:</p>
|
||
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token plain">uv cache clean openrag</span><br></span></code></pre></div></div>
|
||
</li>
|
||
<li class="">
|
||
<p>Invoke OpenRAG to restart the TUI:</p>
|
||
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token plain">uvx openrag</span><br></span></code></pre></div></div>
|
||
</li>
|
||
<li class="">
|
||
<p>Click <strong>Launch OpenRAG</strong>, and then retry document ingestion.</p>
|
||
</li>
|
||
</ol>
|
||
<p>If you install OpenRAG with <code>uv</code>, dependencies are synced directly from your <code>pyproject.toml</code> file.
|
||
This should automatically install <code>easyocr</code> because <code>easyocr</code> is included as a dependency in OpenRAG's <code>pyproject.toml</code>.</p>
|
||
<p>If you don't need OCR, you can disable OCR-based processing in your <a class="" href="/knowledge#knowledge-ingestion-settings">ingestion settings</a> to avoid requiring <code>easyocr</code>.</p>
|
||
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="langflow-container-already-exists-during-upgrade">Upgrade fails due to Langflow container already exists<a href="#langflow-container-already-exists-during-upgrade" class="hash-link" aria-label="Direct link to Upgrade fails due to Langflow container already exists" title="Direct link to Upgrade fails due to Langflow container already exists" translate="no"></a></h2>
|
||
<p>If you encounter a <code>langflow container already exists</code> error when upgrading OpenRAG, this typically means you upgraded OpenRAG with <code>uv</code>, but you didn't remove or upgrade containers from a previous installation.</p>
|
||
<p>To resolve this issue, do the following:</p>
|
||
<ol>
|
||
<li class="">
|
||
<p>Remove only the Langflow container:</p>
|
||
<ol>
|
||
<li class="">
|
||
<p>Stop the Langflow container:</p>
|
||
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_OeMC">Docker</div><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">docker</span><span class="token plain"> stop langflow</span><br></span></code></pre></div></div>
|
||
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_OeMC">Podman</div><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">podman</span><span class="token plain"> stop langflow</span><br></span></code></pre></div></div>
|
||
</li>
|
||
<li class="">
|
||
<p>Remove the Langflow container:</p>
|
||
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_OeMC">Docker</div><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">docker</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">rm</span><span class="token plain"> langflow </span><span class="token parameter variable" style="color:#36acaa">--force</span><br></span></code></pre></div></div>
|
||
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_OeMC">Podman</div><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">podman</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">rm</span><span class="token plain"> langflow </span><span class="token parameter variable" style="color:#36acaa">--force</span><br></span></code></pre></div></div>
|
||
</li>
|
||
</ol>
|
||
</li>
|
||
<li class="">
|
||
<p>Retry the <a class="" href="/upgrade">upgrade</a>.</p>
|
||
</li>
|
||
<li class="">
|
||
<p>If reinstalling the Langflow container doesn't resolve the issue, then you must <a class="" href="/manage-services">reset all containers</a> or <a class="" href="/reinstall">reinstall OpenRAG</a>.</p>
|
||
</li>
|
||
<li class="">
|
||
<p>Retry the <a class="" href="/upgrade">upgrade</a>.</p>
|
||
<p>If no updates are available after reinstalling OpenRAG, then you reinstalled at the latest version, and your deployment is up to date.</p>
|
||
</li>
|
||
</ol>
|
||
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="document-ingestion-or-similarity-search-issues">Document ingestion or similarity search issues<a href="#document-ingestion-or-similarity-search-issues" class="hash-link" aria-label="Direct link to Document ingestion or similarity search issues" title="Direct link to Document ingestion or similarity search issues" translate="no"></a></h2>
|
||
<p>See <a class="" href="/ingestion#troubleshoot-ingestion">Troubleshoot ingestion</a>.</p>
|
||
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="ollama-model-issues">Ollama model issues<a href="#ollama-model-issues" class="hash-link" aria-label="Direct link to Ollama model issues" title="Direct link to Ollama model issues" translate="no"></a></h2>
|
||
<p>OpenRAG isn't guaranteed to be compatible with all models that are available through Ollama.
|
||
For example, some models might produce unexpected results, such as JSON-formatted output instead of natural language responses, and some models aren't appropriate for the types of tasks that OpenRAG performs, such as those that generate media.</p>
|
||
<p>The OpenRAG team recommends the following models when using Ollama as your model provider:</p>
|
||
<ul>
|
||
<li class="">
|
||
<p><strong>Language models</strong>: <code>gpt-oss:20b</code> or <code>mistral-nemo:12b</code>.</p>
|
||
<p>If you choose <code>gpt-oss:20b</code>, consider using Ollama Cloud or running Ollama on a remote machine because this model requires at least 16GB of RAM.</p>
|
||
</li>
|
||
<li class="">
|
||
<p><strong>Embedding models</strong>: <a href="https://ollama.com/library/nomic-embed-text" target="_blank" rel="noopener noreferrer" class=""><code>nomic-embed-text:latest</code></a>, <code>mxbai-embed-large:latest</code>, or <code>embeddinggemma:latest</code>.</p>
|
||
</li>
|
||
</ul>
|
||
<p>You can experiment with other models, but if you encounter issues that you are unable to resolve through other RAG best practices (like context filters and prompt engineering), try switching to one of the recommended models.
|
||
You can submit an <a href="https://github.com/langflow-ai/openrag/issues" target="_blank" rel="noopener noreferrer" class="">OpenRAG GitHub issue</a> to request support for specific models.</p>
|
||
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="chat-issues">Chat issues<a href="#chat-issues" class="hash-link" aria-label="Direct link to Chat issues" title="Direct link to Chat issues" translate="no"></a></h2>
|
||
<p>See <a class="" href="/chat#troubleshoot-chat">Troubleshoot chat</a>.</p></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="row margin-top--sm theme-doc-footer-edit-meta-row"><div class="col noPrint_WFHX"><a href="https://github.com/openrag/openrag/tree/main/docs/docs/support/troubleshoot.mdx" target="_blank" rel="noopener noreferrer" class="theme-edit-this-page"><svg fill="currentColor" height="20" width="20" viewBox="0 0 40 40" class="iconEdit_Z9Sw" aria-hidden="true"><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"></path></g></svg>Edit this page</a></div><div class="col lastUpdated_JAkA"></div></div></footer></article><nav class="docusaurus-mt-lg pagination-nav" aria-label="Docs pages"><a class="pagination-nav__link pagination-nav__link--prev" href="/support/contribute"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">Contribute to OpenRAG</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_bqdL thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href="#installation-and-start-up-issues" class="table-of-contents__link toc-highlight">Installation and start up issues</a><ul><li><a href="#opensearch-fails-to-start" class="table-of-contents__link toc-highlight">OpenSearch fails to start</a></li><li><a href="#openrag-fails-to-start-from-the-tui-with-operation-not-supported" class="table-of-contents__link toc-highlight">OpenRAG fails to start from the TUI with operation not supported</a></li><li><a href="#openrag-installation-fails-with-unable-to-get-local-issuer-certificate" class="table-of-contents__link toc-highlight">OpenRAG installation fails with unable to get local issuer certificate</a></li><li><a href="#application-onboarding-gets-stuck-on-google-chrome" class="table-of-contents__link toc-highlight">Application onboarding gets stuck on Google Chrome</a></li></ul></li><li><a href="#langflow-connection-issues" class="table-of-contents__link toc-highlight">Langflow connection issues</a></li><li><a href="#container-out-of-memory-errors" class="table-of-contents__link toc-highlight">Container out of memory errors</a></li><li><a href="#memory-issue-with-podman-on-macos" class="table-of-contents__link toc-highlight">Memory issue with Podman on macOS</a></li><li><a href="#port-conflicts" class="table-of-contents__link toc-highlight">Port conflicts</a></li><li><a href="#ocr-ingestion-fails-easyocr-not-installed" class="table-of-contents__link toc-highlight">OCR ingestion fails (easyocr not installed)</a></li><li><a href="#langflow-container-already-exists-during-upgrade" class="table-of-contents__link toc-highlight">Upgrade fails due to Langflow container already exists</a></li><li><a href="#document-ingestion-or-similarity-search-issues" class="table-of-contents__link toc-highlight">Document ingestion or similarity search issues</a></li><li><a href="#ollama-model-issues" class="table-of-contents__link toc-highlight">Ollama model issues</a></li><li><a href="#chat-issues" class="table-of-contents__link toc-highlight">Chat issues</a></li></ul></div></div></div></div></main></div></div></div><footer class="theme-layout-footer footer"><div class="container container-fluid"><div class="row footer__links"><div class="theme-layout-footer-column col footer__col"><div class="footer__title"></div><ul class="footer__items clean-list"><li class="footer__item"><div class="footer-links">
|
||
<span>© 2026 OpenRAG</span>
|
||
</div></li></ul></div></div></div></footer></div>
|
||
</body>
|
||
</html> |