Problem: Open WebUI knowledge base retrieval not working / embedding misconfigured (file upload fails with Ollama embed 404) —— Trove problem library

What you will run into

You create a knowledge base in Open WebUI, upload a document, and the file stays failed:

Ollama embed error (404): model "nomic-embed-text" not found, try pulling it first

The model is pulled, Ollama is reachable (chat shows the models), but embedding just won't work. Tutorials tell you to set OLLAMA_BASE_URLS and RAG_EMBEDDING_MODEL; you set them all and it still 404s.

There are three layers of traps — miss any one and you get 404.

Why this happens

The embedding chain has three independent settings; any of them wrong → 404:

Also note: default RELEVANCE_THRESHOLD=0 returns top-k even for unrelated queries — that does not mean retrieval is broken.

The embedding chain is "model name → embedding service address → storage config" in three serial hops; any broken hop shows up as "upload failed / retrieval 404".

The three mechanics: ① a model name prefixed with ollama/ is forwarded verbatim to ollama (the engine name is not a namespace), and ollama cannot find ollama/nomic-embed-text, so it 404s;

② the embedding service address is a separate config key RAG_OLLAMA_BASE_URL (DB rag.ollama.base_url), unrelated to the chat-facing OLLAMA_BASE_URLS — when unset it falls back to the image default (which may point at an instance without the embedding model);

③ config is persisted into the DB on first startup (SQLite config table), after which env vars no longer apply — DB wins over env, which is why "change env and restart" does nothing.

Deterministic takeaway: classify the scenario first — existing instance: update the DB config via the management API (/api/v1/retrieval/embedding/update); fresh container: pass everything at startup;

verify by uploading a file and watching vectorization succeed (seconds-level), not by staring at the config page;

with RELEVANCE_THRESHOLD=0, irrelevant queries returning top-k is normal, not a broken retriever.

Official troubleshooting reference (docs.openwebui.com/troubleshooting/rag/)

Directly relevant entries from the official RAG troubleshooting doc, side by side with this page's three-trap chain:

Correct API upload flow (official wait_for_processing pattern, avoids the empty-content race):

import requests, time

def wait_for_processing(token, file_id, timeout=300):
    url = f'http://localhost:3000/api/v1/files/{file_id}/process/status"
    headers = {"Authorization": f'Bearer {token}"}
    start = time.time
    while time.time - start < timeout:
        r = requests.get(url, headers=headers).json
        if r.get("status") == "completed":
            return True
        if r.get("status") == "failed":
            raise RuntimeError(f'Processing failed: {r.get('error')}")
        time.sleep(2)          # poll every 2 seconds
    raise TimeoutError("file processing timed out")

One observation consistent with this page's test: with RELEVANCE_THRESHOLD at its default 0, unrelated queries still return top-k results — retrieval isn't broken; raise the threshold to filter.

Step by step

1. Probe Ollama directly: model and naming — Diagnose (30s: model problem vs config problem)

# bare name (correct): 200 with embeddings
curl -s http://localhost:11434/api/embed -d '{"model":"nomic-embed-text","input":["test"]}' | head -c 200
# ollama/ prefix (wrong): 404 model "ollama/nomic-embed-text" not found
curl -s http://localhost:11434/api/embed -d '{"model":"ollama/nomic-embed-text","input":["test"]}'

Model missing: ollama pull nomic-embed-text (274MB; small models on the official registry are usually fine).

2. Read the exact failure of the file — Diagnose (read the error, layer by layer)

If the error is Ollama embed error (404) it's the three traps above; if it's Connection refused, that's the connectivity issue (see open-webui-ollama-connect).

3. Existing volume: use the admin API, not env — Required (config change; env won't work after first boot)

# Check the effective value (DB wins)
docker exec open-webui python3 -c "import sqlite3; con=sqlite3.connect('/app/backend/data/webui.db'); print(con.execute(\"SELECT key,value FROM config WHERE key='rag.ollama.base_url'\").fetchone)"
# Override via admin API (UI equivalent: Admin → Settings → Retrieval → embedding)
curl -X POST http://localhost:3000/api/v1/retrieval/embedding/update \
  -H "Authorization: Bearer <token>" -H 'Content-Type: application/json' \
  -d '{"RAG_EMBEDDING_ENGINE":"ollama","RAG_EMBEDDING_MODEL":"nomic-embed-text","ollama_config":{"url":"http://host.docker.internal:11434","key":""}}'

4. Delete the failed file and re-upload — Required (old files don't retry)

Upload → wait for status completed (seconds). Still failed? Read the error text and walk the layers.

5. Create KB → add file → query — Required (acceptance)

# create knowledge base → kb_id
curl -X POST http://localhost:3000/api/v1/knowledge/create -H "Authorization: Bearer <token>" -H 'Content-Type: application/json' -d '{"name":"kb"}'
# add file (file_id from the upload response)
curl -X POST http://localhost:3000/api/v1/knowledge/<kb_id>/file/add -H "Authorization: Bearer <token>" -H 'Content-Type: application/json' -d '{"file_id":"<file_id>"}'
# query
curl -X POST http://localhost:3000/api/v1/retrieval/query/collection -H "Authorization: Bearer <token>" -H 'Content-Type: application/json' -d '{"collection_names":["<kb_id>"],"query":"a keyword from the doc","k":3}'

How to confirm it works

• The uploaded file is completed (not failed); logs show embeddings generated ... added ... to collection.
• The query hits the document content and the metadata embedding_config is correct: {'engine': 'ollama', 'model': 'nomic-embed-text'}.
• Direct POST /api/embed with the bare name returns 200 (768-dim vector); the prefixed name returning 404 is expected.
• Note: unrelated queries returning results ≠ broken (default threshold 0 returns top-k); raise RELEVANCE_THRESHOLD in settings if you want filtering.

Other environments

Symptom

• Knowledge-base files stuck at failed, error contains Ollama embed error (404): model "nomic-embed-text" not found, try pulling it first;
• The model list shows the embedding model and chat works, but KB retrieval doesn't;
• Set OLLAMA_BASE_URLS / RAG_EMBEDDING_MODEL per tutorials, restarted, still 404.

Cause

• Model name written with an ollama/ prefix (404);
• The embedding URL is a separate setting RAG_OLLAMA_BASE_URL, which falls back to a default instance (possibly without the model);
• After first start the config is persisted in SQLite and DB wins over env; env changes are ignored.

Solution

1. Probe POST /api/embed: bare name 200 / prefixed 404; 2. ollama pull the embedding model; 3. Existing volumes: admin API POST /api/v1/retrieval/embedding/update with ollama_config.url (env won't work); 4. Delete failed files and re-upload, wait for completed; 5. Create KB + add file + query to verify; 6. If unrelated queries return top-k, raise RELEVANCE_THRESHOLD.

Related canonicals

Read in order: precondition -> same root / same domain / related:

• Same root:
• Forgot the admin password / can't log in (same root: webui.db is the single source of truth (config table and auth table both beat env/signup))

• Related (similar errors, different cause):
• Open WebUI shows "cannot connect to Ollama" (Connection refused cases; host.docker.internal and OLLAMA_BASE_URLS)
• ollama pull stuck/timeout (slow embedding model downloads)
• Move the model directory (embedding models move with the directory)

References

• Open WebUI official RAG troubleshooting — <https://docs.openwebui.com/troubleshooting/rag/>