1 line
No EOL
13 KiB
JavaScript
1 line
No EOL
13 KiB
JavaScript
"use strict";(self.webpackChunkopenrag_docs=self.webpackChunkopenrag_docs||[]).push([[2668],{5014:(e,n,s)=>{s.r(n),s.d(n,{assets:()=>d,contentTitle:()=>c,default:()=>u,frontMatter:()=>t,metadata:()=>r,toc:()=>h});const r=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),a=s(8453),i=s(1470),l=s(9365);const t={title:"Troubleshoot OpenRAG",slug:"/support/troubleshoot"},c=void 0,d={},h=[{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}];function p(e){const n={a:"a",admonition:"admonition",code:"code",h2:"h2",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",...(0,a.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 ",(0,o.jsx)(n.code,{children:"OPENSEARCH_PASSWORD"})," set in ",(0,o.jsx)(n.a,{href:"/reference/configuration",children:"Environment variables"})," meets requirements.\nThe password must contain at least 8 characters, and must contain at least one uppercase letter, one lowercase letter, one digit, and one special character that is strong."]}),"\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 the ",(0,o.jsx)(n.code,{children:"LANGFLOW_SUPERUSER"})," credentials set in ",(0,o.jsx)(n.a,{href:"/reference/configuration",children:"Environment variables"})," are correct."]}),"\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.jsx)(n.p,{children:"Ensure ports 3000, 7860, 8000, 9200, 5601 are available."}),"\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:["If Docling ingestion fails with an OCR-related error and mentions ",(0,o.jsx)(n.code,{children:"easyocr"})," is missing, this is likely due to a stale ",(0,o.jsx)(n.code,{children:"uv"})," cache."]}),"\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.code,{children:"easyocr"})," is already included as a dependency in OpenRAG's ",(0,o.jsx)(n.code,{children:"pyproject.toml"}),". Project-managed installations using ",(0,o.jsx)(n.code,{children:"uv sync"})," and ",(0,o.jsx)(n.code,{children:"uv run"})," always sync dependencies directly from your ",(0,o.jsx)(n.code,{children:"pyproject.toml"}),", so they should have ",(0,o.jsx)(n.code,{children:"easyocr"})," installed."]}),"\n",(0,o.jsxs)(n.p,{children:["If you're running 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. This cache can become stale."]}),"\n",(0,o.jsxs)(n.p,{children:["On macOS, this cache directory is typically a user cache directory such as ",(0,o.jsx)(n.code,{children:"/Users/USER_NAME/.cache/uv"}),"."]}),"\n",(0,o.jsxs)(n.ol,{children:["\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"To clear the uv cache, run:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"uv cache clean\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Start OpenRAG:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"uvx openrag\n"})}),"\n"]}),"\n"]}),"\n",(0,o.jsxs)(n.p,{children:["If you do not need OCR, you can disable OCR-based processing in your 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.p,{children:["First, try removing only the Langflow container, and then retry the upgrade in the OpenRAG TUI by clicking ",(0,o.jsx)(n.strong,{children:"Status"})," and then ",(0,o.jsx)(n.strong,{children:"Upgrade"}),"."]}),"\n",(0,o.jsxs)(i.A,{groupId:"Container software",children:[(0,o.jsx)(l.A,{value:"Podman",label:"Podman",children:(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",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",children:"podman rm langflow --force\n"})}),"\n"]}),"\n"]})}),(0,o.jsx)(l.A,{value:"Docker",label:"Docker",default:!0,children:(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",children:"docker 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",children:"docker rm langflow --force\n"})}),"\n"]}),"\n"]})})]}),"\n",(0,o.jsx)(n.p,{children:"If reinstalling the Langflow container doesn't resolve the issue, you must reset to a fresh installation by removing all OpenRAG containers and data.\nThen, you can retry the upgrade."}),"\n",(0,o.jsx)(n.admonition,{type:"warning",children:(0,o.jsxs)(n.p,{children:["This is a destructive operation that completely resets your OpenRAG containers and removes all OpenRAG data, including OpenSearch data, uploaded documents, and authentication details.\nYour ",(0,o.jsx)(n.code,{children:".env"})," file is preserved, so your configuration settings remain intact, but all other data is lost."]})}),"\n",(0,o.jsxs)(n.p,{children:["To reset your installation, stop your containers, and then completely remove them.\nAfter removing the containers, retry the upgrade in the OpenRAG TUI by clicking ",(0,o.jsx)(n.strong,{children:"Status"})," and then ",(0,o.jsx)(n.strong,{children:"Upgrade"}),"."]}),"\n",(0,o.jsxs)(i.A,{groupId:"Container software",children:[(0,o.jsx)(l.A,{value:"Podman",label:"Podman",children:(0,o.jsxs)(n.ol,{children:["\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Stop all running containers:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"podman stop --all\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove all containers, including stopped containers:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"podman rm --all --force\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove all images:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"podman rmi --all --force\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove all volumes:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"podman volume prune --force\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove all networks except the default network:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"podman network prune --force\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Clean up any leftover data:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"podman system prune --all --force --volumes\n"})}),"\n"]}),"\n"]})}),(0,o.jsx)(l.A,{value:"Docker",label:"Docker",default:!0,children:(0,o.jsxs)(n.ol,{children:["\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Stop all running containers:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"docker stop $(docker ps -q)\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove all containers, including stopped containers:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"docker rm --force $(docker ps -aq)\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove all images:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"docker rmi --force $(docker images -q)\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove all volumes:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"docker volume prune --force\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Remove all networks except the default network:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"docker network prune --force\n"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:"Clean up any leftover data:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"docker system prune --all --force --volumes\n"})}),"\n"]}),"\n"]})})]})]})}function u(e={}){const{wrapper:n}={...(0,a.R)(),...e.components};return n?(0,o.jsx)(n,{...e,children:(0,o.jsx)(p,{...e})}):p(e)}}}]); |