1 line
No EOL
12 KiB
JavaScript
1 line
No EOL
12 KiB
JavaScript
"use strict";(globalThis.webpackChunkopenrag_docs=globalThis.webpackChunkopenrag_docs||[]).push([[2668],{5014:(e,n,s)=>{s.r(n),s.d(n,{assets:()=>l,contentTitle:()=>a,default:()=>d,frontMatter:()=>t,metadata:()=>i,toc:()=>c});const i=JSON.parse('{"id":"support/troubleshoot","title":"Troubleshoot OpenRAG","description":"This page provides troubleshooting advice for issues you might encounter when using OpenRAG or contributing to OpenRAG.","source":"@site/docs/support/troubleshoot.mdx","sourceDirName":"support","slug":"/support/troubleshoot","permalink":"/support/troubleshoot","draft":false,"unlisted":false,"editUrl":"https://github.com/openrag/openrag/tree/main/docs/docs/support/troubleshoot.mdx","tags":[],"version":"current","frontMatter":{"title":"Troubleshoot OpenRAG","slug":"/support/troubleshoot"},"sidebar":"tutorialSidebar","previous":{"title":"Environment variables","permalink":"/reference/configuration"}}');var o=s(4848),r=s(8453);const t={title:"Troubleshoot OpenRAG",slug:"/support/troubleshoot"},a=void 0,l={},c=[{value:"OpenSearch fails to start",id:"opensearch-fails-to-start",level:2},{value:"OpenRAG fails to start from the TUI with operation not supported",id:"openrag-fails-to-start-from-the-tui-with-operation-not-supported",level:2},{value:"OpenRAG installation fails with unable to get local issuer certificate",id:"openrag-installation-fails-with-unable-to-get-local-issuer-certificate",level:2},{value:"Langflow connection issues",id:"langflow-connection-issues",level:2},{value:"Container out of memory errors",id:"container-out-of-memory-errors",level:2},{value:"Memory issue with Podman on macOS",id:"memory-issue-with-podman-on-macos",level:2},{value:"Port conflicts",id:"port-conflicts",level:2},{value:"OCR ingestion fails (easyocr not installed)",id:"ocr-ingestion-fails-easyocr-not-installed",level:2},{value:"Upgrade fails due to Langflow container already exists",id:"langflow-container-already-exists-during-upgrade",level:2},{value:"Document ingestion or similarity search issues",id:"document-ingestion-or-similarity-search-issues",level:2}];function h(e){const n={a:"a",code:"code",h2:"h2",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,r.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(n.p,{children:"This page provides troubleshooting advice for issues you might encounter when using OpenRAG or contributing to OpenRAG."}),"\n",(0,o.jsx)(n.h2,{id:"opensearch-fails-to-start",children:"OpenSearch fails to start"}),"\n",(0,o.jsxs)(n.p,{children:["Check that the value of the ",(0,o.jsx)(n.code,{children:"OPENSEARCH_PASSWORD"})," ",(0,o.jsx)(n.a,{href:"/reference/configuration",children:"environment variable"})," meets the ",(0,o.jsx)(n.a,{href:"https://docs.opensearch.org/latest/security/configuration/demo-configuration/#setting-up-a-custom-admin-password",children:"OpenSearch password complexity requirements"}),"."]}),"\n",(0,o.jsxs)(n.p,{children:["If you need to change the password, you must ",(0,o.jsx)(n.a,{href:"/manage-services",children:"reset the OpenRAG services"}),"."]}),"\n",(0,o.jsx)(n.h2,{id:"openrag-fails-to-start-from-the-tui-with-operation-not-supported",children:"OpenRAG fails to start from the TUI with operation not supported"}),"\n",(0,o.jsxs)(n.p,{children:["This error occurs when starting OpenRAG with the TUI in ",(0,o.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/install",children:"WSL (Windows Subsystem for Linux)"}),"."]}),"\n",(0,o.jsxs)(n.p,{children:["The error occurs because OpenRAG is running within a WSL environment, so ",(0,o.jsx)(n.code,{children:"webbrowser.open()"})," can't launch a browser automatically."]}),"\n",(0,o.jsxs)(n.p,{children:["To access the OpenRAG application, open a web browser and enter ",(0,o.jsx)(n.code,{children:"http://localhost:3000"})," in the address bar."]}),"\n",(0,o.jsx)(n.h2,{id:"openrag-installation-fails-with-unable-to-get-local-issuer-certificate",children:"OpenRAG installation fails with unable to get local issuer certificate"}),"\n",(0,o.jsxs)(n.p,{children:["If you are installing OpenRAG on macOS, and the installation fails with ",(0,o.jsx)(n.code,{children:"unable to get local issuer certificate"}),", run the following command, and then retry the installation:"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:'open "/Applications/Python VERSION/Install Certificates.command"\n'})}),"\n",(0,o.jsxs)(n.p,{children:["Replace ",(0,o.jsx)(n.code,{children:"VERSION"})," with your installed Python version, such as ",(0,o.jsx)(n.code,{children:"3.13"}),"."]}),"\n",(0,o.jsx)(n.h2,{id:"langflow-connection-issues",children:"Langflow connection issues"}),"\n",(0,o.jsxs)(n.p,{children:["Verify that the value of the ",(0,o.jsx)(n.code,{children:"LANGFLOW_SUPERUSER"})," environment variable is correct.\nFor more information about this variable and how this variable controls Langflow access, see ",(0,o.jsx)(n.a,{href:"/reference/configuration#langflow-settings",children:"Langflow settings"}),"."]}),"\n",(0,o.jsx)(n.h2,{id:"container-out-of-memory-errors",children:"Container out of memory errors"}),"\n",(0,o.jsxs)(n.p,{children:["Increase Docker memory allocation or use ",(0,o.jsx)(n.a,{href:"https://github.com/langflow-ai/openrag/blob/main/docker-compose-cpu.yml",children:"docker-compose-cpu.yml"})," to deploy OpenRAG."]}),"\n",(0,o.jsx)(n.h2,{id:"memory-issue-with-podman-on-macos",children:"Memory issue with Podman on macOS"}),"\n",(0,o.jsx)(n.p,{children:"If you're using Podman on macOS, you might need to increase VM memory on your Podman machine.\nThis example increases the machine size to 8 GB of RAM, which should be sufficient to run OpenRAG."}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"podman machine stop\npodman machine rm\npodman machine init --memory 8192 # 8 GB example\npodman machine start\n"})}),"\n",(0,o.jsx)(n.h2,{id:"port-conflicts",children:"Port conflicts"}),"\n",(0,o.jsxs)(n.p,{children:["With the default ",(0,o.jsx)(n.a,{href:"/reference/configuration",children:"environment variable"})," values, OpenRAG requires the following ports to be available on the host machine:"]}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:"3000: Langflow application"}),"\n",(0,o.jsx)(n.li,{children:"5001: Docling local ingestion service"}),"\n",(0,o.jsx)(n.li,{children:"5601: OpenSearch Dashboards"}),"\n",(0,o.jsx)(n.li,{children:"7860: Docling UI"}),"\n",(0,o.jsx)(n.li,{children:"8000: Docling API"}),"\n",(0,o.jsx)(n.li,{children:"9200: OpenSearch service"}),"\n"]}),"\n",(0,o.jsx)(n.h2,{id:"ocr-ingestion-fails-easyocr-not-installed",children:"OCR ingestion fails (easyocr not installed)"}),"\n",(0,o.jsxs)(n.p,{children:["Docling ingestion can fail with an OCR-related error that mentions ",(0,o.jsx)(n.code,{children:"easyocr"})," is missing.\nThis is likely due to a stale ",(0,o.jsx)(n.code,{children:"uv"})," cache when you ",(0,o.jsxs)(n.a,{href:"/install-uvx",children:["install OpenRAG with ",(0,o.jsx)(n.code,{children:"uvx"})]}),"."]}),"\n",(0,o.jsxs)(n.p,{children:["When you invoke OpenRAG with ",(0,o.jsx)(n.code,{children:"uvx openrag"}),", ",(0,o.jsx)(n.code,{children:"uvx"})," creates a cached, ephemeral environment that doesn't modify your project.\nThe location and path of this cache depends on your operating system.\nFor example, on macOS, this is typically a user cache directory, such as ",(0,o.jsx)(n.code,{children:"/Users/USER_NAME/.cache/uv"}),"."]}),"\n",(0,o.jsx)(n.p,{children:"This cache can become stale, producing errors like missing dependencies."}),"\n",(0,o.jsxs)(n.ol,{children:["\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.a,{href:"/tui",children:"Exit the TUI"}),"."]}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsxs)(n.p,{children:["Clear the ",(0,o.jsx)(n.code,{children:"uv"})," cache:"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"uv cache clean\n"})}),"\n",(0,o.jsx)(n.p,{children:"To clear the OpenRAG cache only, run:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"uv cache clean openrag\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Invoke OpenRAG to restart the TUI:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"uvx openrag\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsxs)(n.p,{children:["Click ",(0,o.jsx)(n.strong,{children:"Open App"}),", and then retry document ingestion."]}),"\n"]}),"\n"]}),"\n",(0,o.jsxs)(n.p,{children:["If you install OpenRAG with ",(0,o.jsx)(n.code,{children:"uv"}),", dependencies are synced directly from your ",(0,o.jsx)(n.code,{children:"pyproject.toml"})," file.\nThis should automatically install ",(0,o.jsx)(n.code,{children:"easyocr"})," because ",(0,o.jsx)(n.code,{children:"easyocr"})," is included as a dependency in OpenRAG's ",(0,o.jsx)(n.code,{children:"pyproject.toml"}),"."]}),"\n",(0,o.jsxs)(n.p,{children:["If you don't need OCR, you can disable OCR-based processing in your ",(0,o.jsx)(n.a,{href:"/knowledge#knowledge-ingestion-settings",children:"ingestion settings"})," to avoid requiring ",(0,o.jsx)(n.code,{children:"easyocr"}),"."]}),"\n",(0,o.jsx)(n.h2,{id:"langflow-container-already-exists-during-upgrade",children:"Upgrade fails due to Langflow container already exists"}),"\n",(0,o.jsxs)(n.p,{children:["If you encounter a ",(0,o.jsx)(n.code,{children:"langflow container already exists"})," error when upgrading OpenRAG, this typically means you upgraded OpenRAG with ",(0,o.jsx)(n.code,{children:"uv"}),", but you didn't remove or upgrade containers from a previous installation."]}),"\n",(0,o.jsx)(n.p,{children:"To resolve this issue, do the following:"}),"\n",(0,o.jsxs)(n.ol,{children:["\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove only the Langflow container:"}),"\n",(0,o.jsxs)(n.ol,{children:["\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Stop the Langflow container:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",metastring:'title="Docker"',children:"docker stop langflow\n"})}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",metastring:'title="Podman"',children:"podman stop langflow\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove the Langflow container:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",metastring:'title="Docker"',children:"docker rm langflow --force\n"})}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",metastring:'title="Podman"',children:"podman rm langflow --force\n"})}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsxs)(n.p,{children:["Retry the ",(0,o.jsx)(n.a,{href:"/upgrade",children:"upgrade"}),"."]}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsxs)(n.p,{children:["If reinstalling the Langflow container doesn't resolve the issue, then you must ",(0,o.jsx)(n.a,{href:"/manage-services",children:"reset all containers"})," or ",(0,o.jsx)(n.a,{href:"/reinstall",children:"reinstall OpenRAG"}),"."]}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsxs)(n.p,{children:["Retry the ",(0,o.jsx)(n.a,{href:"/upgrade",children:"upgrade"}),"."]}),"\n",(0,o.jsx)(n.p,{children:"If no updates are available after reinstalling OpenRAG, then you reinstalled at the latest version, and your deployment is up to date."}),"\n"]}),"\n"]}),"\n",(0,o.jsx)(n.h2,{id:"document-ingestion-or-similarity-search-issues",children:"Document ingestion or similarity search issues"}),"\n",(0,o.jsxs)(n.p,{children:["See ",(0,o.jsx)(n.a,{href:"/ingestion#troubleshoot-ingestion",children:"Troubleshoot ingestion"}),"."]})]})}function d(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,o.jsx)(n,{...e,children:(0,o.jsx)(h,{...e})}):h(e)}},8453:(e,n,s)=>{s.d(n,{R:()=>t,x:()=>a});var i=s(6540);const o={},r=i.createContext(o);function t(e){const n=i.useContext(r);return i.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function a(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(o):e.components||o:t(e.components),i.createElement(r.Provider,{value:n},e.children)}}}]); |