1 line
No EOL
14 KiB
JavaScript
1 line
No EOL
14 KiB
JavaScript
"use strict";(globalThis.webpackChunkopenrag_docs=globalThis.webpackChunkopenrag_docs||[]).push([[2668],{3059:(e,n,s)=>{s.d(n,{Ay:()=>l,RM:()=>r});var o=s(4848),i=s(8453);const r=[];function t(e){const n={a:"a",code:"code",li:"li",p:"p",strong:"strong",ul:"ul",...(0,i.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(n.p,{children:"OpenRAG isn't guaranteed to be compatible with all models that are available through Ollama.\nFor 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."}),"\n",(0,o.jsx)(n.p,{children:"The OpenRAG team recommends the following models when using Ollama as your model provider:"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"Language models"}),": ",(0,o.jsx)(n.code,{children:"gpt-oss:20b"})," or ",(0,o.jsx)(n.code,{children:"mistral-nemo:12b"}),"."]}),"\n",(0,o.jsxs)(n.p,{children:["If you choose ",(0,o.jsx)(n.code,{children:"gpt-oss:20b"}),", consider using Ollama Cloud or running Ollama on a remote machine because this model requires at least 16GB of RAM."]}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"Embedding models"}),": ",(0,o.jsx)(n.a,{href:"https://ollama.com/library/nomic-embed-text",children:(0,o.jsx)(n.code,{children:"nomic-embed-text:latest"})}),", ",(0,o.jsx)(n.code,{children:"mxbai-embed-large:latest"}),", or ",(0,o.jsx)(n.code,{children:"embeddinggemma:latest"}),"."]}),"\n"]}),"\n"]}),"\n",(0,o.jsxs)(n.p,{children:["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.\nYou can submit an ",(0,o.jsx)(n.a,{href:"https://github.com/langflow-ai/openrag/issues",children:"OpenRAG GitHub issue"})," to request support for specific models."]})]})}function l(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,o.jsx)(n,{...e,children:(0,o.jsx)(t,{...e})}):t(e)}},5014:(e,n,s)=>{s.r(n),s.d(n,{assets:()=>c,contentTitle:()=>a,default:()=>u,frontMatter:()=>l,metadata:()=>o,toc:()=>d});const o=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 i=s(4848),r=s(8453),t=s(3059);const l={title:"Troubleshoot OpenRAG",slug:"/support/troubleshoot"},a=void 0,c={},d=[{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},{value:"Ollama model issues",id:"ollama-model-issues",level:2},...t.RM];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,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(n.p,{children:"This page provides troubleshooting advice for issues you might encounter when using OpenRAG or contributing to OpenRAG."}),"\n",(0,i.jsx)(n.h2,{id:"opensearch-fails-to-start",children:"OpenSearch fails to start"}),"\n",(0,i.jsxs)(n.p,{children:["Check that the value of the ",(0,i.jsx)(n.code,{children:"OPENSEARCH_PASSWORD"})," ",(0,i.jsx)(n.a,{href:"/reference/configuration",children:"environment variable"})," meets the ",(0,i.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,i.jsxs)(n.p,{children:["If you need to change the password, you must ",(0,i.jsx)(n.a,{href:"/manage-services",children:"reset the OpenRAG services"}),"."]}),"\n",(0,i.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,i.jsxs)(n.p,{children:["This error occurs when starting OpenRAG with the TUI in ",(0,i.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/install",children:"WSL (Windows Subsystem for Linux)"}),"."]}),"\n",(0,i.jsxs)(n.p,{children:["The error occurs because OpenRAG is running within a WSL environment, so ",(0,i.jsx)(n.code,{children:"webbrowser.open()"})," can't launch a browser automatically."]}),"\n",(0,i.jsxs)(n.p,{children:["To access the OpenRAG application, open a web browser and enter ",(0,i.jsx)(n.code,{children:"http://localhost:3000"})," in the address bar."]}),"\n",(0,i.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,i.jsxs)(n.p,{children:["If you are installing OpenRAG on macOS, and the installation fails with ",(0,i.jsx)(n.code,{children:"unable to get local issuer certificate"}),", run the following command, and then retry the installation:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:'open "/Applications/Python VERSION/Install Certificates.command"\n'})}),"\n",(0,i.jsxs)(n.p,{children:["Replace ",(0,i.jsx)(n.code,{children:"VERSION"})," with your installed Python version, such as ",(0,i.jsx)(n.code,{children:"3.13"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"langflow-connection-issues",children:"Langflow connection issues"}),"\n",(0,i.jsxs)(n.p,{children:["Verify that the value of the ",(0,i.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,i.jsx)(n.a,{href:"/reference/configuration#langflow-settings",children:"Langflow settings"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"container-out-of-memory-errors",children:"Container out of memory errors"}),"\n",(0,i.jsxs)(n.p,{children:["Increase Docker memory allocation or use ",(0,i.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,i.jsx)(n.h2,{id:"memory-issue-with-podman-on-macos",children:"Memory issue with Podman on macOS"}),"\n",(0,i.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,i.jsx)(n.pre,{children:(0,i.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,i.jsx)(n.h2,{id:"port-conflicts",children:"Port conflicts"}),"\n",(0,i.jsxs)(n.p,{children:["With the default ",(0,i.jsx)(n.a,{href:"/reference/configuration",children:"environment variable"})," values, OpenRAG requires the following ports to be available on the host machine:"]}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"3000: Langflow application"}),"\n",(0,i.jsx)(n.li,{children:"5001: Docling local ingestion service"}),"\n",(0,i.jsx)(n.li,{children:"5601: OpenSearch Dashboards"}),"\n",(0,i.jsx)(n.li,{children:"7860: Docling UI"}),"\n",(0,i.jsx)(n.li,{children:"8000: Docling API"}),"\n",(0,i.jsx)(n.li,{children:"9200: OpenSearch service"}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"ocr-ingestion-fails-easyocr-not-installed",children:"OCR ingestion fails (easyocr not installed)"}),"\n",(0,i.jsxs)(n.p,{children:["Docling ingestion can fail with an OCR-related error that mentions ",(0,i.jsx)(n.code,{children:"easyocr"})," is missing.\nThis is likely due to a stale ",(0,i.jsx)(n.code,{children:"uv"})," cache when you ",(0,i.jsxs)(n.a,{href:"/install-uvx",children:["install OpenRAG with ",(0,i.jsx)(n.code,{children:"uvx"})]}),"."]}),"\n",(0,i.jsxs)(n.p,{children:["When you invoke OpenRAG with ",(0,i.jsx)(n.code,{children:"uvx openrag"}),", ",(0,i.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,i.jsx)(n.code,{children:"~/.cache/uv"}),"."]}),"\n",(0,i.jsx)(n.p,{children:"This cache can become stale, producing errors like missing dependencies."}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.a,{href:"/tui",children:"Exit the TUI"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Clear the ",(0,i.jsx)(n.code,{children:"uv"})," cache:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv cache clean\n"})}),"\n",(0,i.jsx)(n.p,{children:"To clear the OpenRAG cache only, run:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv cache clean openrag\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Invoke OpenRAG to restart the TUI:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uvx openrag\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Click ",(0,i.jsx)(n.strong,{children:"Open App"}),", and then retry document ingestion."]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.p,{children:["If you install OpenRAG with ",(0,i.jsx)(n.code,{children:"uv"}),", dependencies are synced directly from your ",(0,i.jsx)(n.code,{children:"pyproject.toml"})," file.\nThis should automatically install ",(0,i.jsx)(n.code,{children:"easyocr"})," because ",(0,i.jsx)(n.code,{children:"easyocr"})," is included as a dependency in OpenRAG's ",(0,i.jsx)(n.code,{children:"pyproject.toml"}),"."]}),"\n",(0,i.jsxs)(n.p,{children:["If you don't need OCR, you can disable OCR-based processing in your ",(0,i.jsx)(n.a,{href:"/knowledge#knowledge-ingestion-settings",children:"ingestion settings"})," to avoid requiring ",(0,i.jsx)(n.code,{children:"easyocr"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"langflow-container-already-exists-during-upgrade",children:"Upgrade fails due to Langflow container already exists"}),"\n",(0,i.jsxs)(n.p,{children:["If you encounter a ",(0,i.jsx)(n.code,{children:"langflow container already exists"})," error when upgrading OpenRAG, this typically means you upgraded OpenRAG with ",(0,i.jsx)(n.code,{children:"uv"}),", but you didn't remove or upgrade containers from a previous installation."]}),"\n",(0,i.jsx)(n.p,{children:"To resolve this issue, do the following:"}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Remove only the Langflow container:"}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Stop the Langflow container:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",metastring:'title="Docker"',children:"docker stop langflow\n"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",metastring:'title="Podman"',children:"podman stop langflow\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Remove the Langflow container:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",metastring:'title="Docker"',children:"docker rm langflow --force\n"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",metastring:'title="Podman"',children:"podman rm langflow --force\n"})}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Retry the ",(0,i.jsx)(n.a,{href:"/upgrade",children:"upgrade"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["If reinstalling the Langflow container doesn't resolve the issue, then you must ",(0,i.jsx)(n.a,{href:"/manage-services",children:"reset all containers"})," or ",(0,i.jsx)(n.a,{href:"/reinstall",children:"reinstall OpenRAG"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Retry the ",(0,i.jsx)(n.a,{href:"/upgrade",children:"upgrade"}),"."]}),"\n",(0,i.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,i.jsx)(n.h2,{id:"document-ingestion-or-similarity-search-issues",children:"Document ingestion or similarity search issues"}),"\n",(0,i.jsxs)(n.p,{children:["See ",(0,i.jsx)(n.a,{href:"/ingestion#troubleshoot-ingestion",children:"Troubleshoot ingestion"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"ollama-model-issues",children:"Ollama model issues"}),"\n",(0,i.jsx)(t.Ay,{})]})}function u(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(h,{...e})}):h(e)}},8453:(e,n,s)=>{s.d(n,{R:()=>t,x:()=>l});var o=s(6540);const i={},r=o.createContext(i);function t(e){const n=o.useContext(r);return o.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function l(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:t(e.components),o.createElement(r.Provider,{value:n},e.children)}}}]); |