Skip to main content

Startup & Docker Failures

Open WebUI not coming up at all? Start here. For failures specifically about Alembic migrations (no such table, Can't locate revision), see Database Migration instead.

Container hangs at startup on Apple Silicon (M1/M2/M3)​

Symptom​

On macOS Apple Silicon, the container freezes during startup right after the migrations finish and this line prints:

WARNING: CORS_ALLOW_ORIGIN IS SET TO '*' - NOT RECOMMENDED FOR PRODUCTION DEPLOYMENTS.

There is no Started server process, no ASCII banner, no error. It hangs indefinitely (still dead after an hour), and it reproduces even on a brand-new empty data volume. OFFLINE_MODE / HF_HUB_OFFLINE make no difference. Stopping it with Ctrl+C leaves the container running, so it has to be killed with docker kill.

Cause​

Nothing of Open WebUI's own logic runs in this window, migrations are already done, and no DB queries or network calls happen yet. It is pure Python import of the app and its native dependencies (pycrdt, embedding/vector libraries, pydub, etc.).

The usual trigger is an architecture mismatch: the host has DOCKER_DEFAULT_PLATFORM=linux/amd64 set globally, so Docker pulls the x86_64 image and runs it under Rosetta emulation on an ARM host. A native extension wedges during import under emulation.

Fix​

Run the native arm64 image, do not emulate x86 on Apple Silicon:

  1. Let Docker auto-select the architecture, or force it explicitly:

    docker run --platform linux/arm64 ... ghcr.io/open-webui/open-webui:main
  2. Check for a global override and unset it (or override per run):

    echo $DOCKER_DEFAULT_PLATFORM     # also check Docker Desktop → Settings
  3. Confirm the architecture the container actually runs as (should be aarch64 on Apple Silicon):

    docker run --rm ghcr.io/open-webui/open-webui:main uname -m
Emulation is not supported

Running the x86 image under emulation (Rosetta) on Apple Silicon is best-effort and unsupported, and can hang at startup like this. Use the native arm64 image.

Capturing the exact blocking import

If a startup hang is not arch-related, dump every thread's stack after 60s (no install needed, faulthandler is stdlib):

docker run --rm --entrypoint python ghcr.io/open-webui/open-webui:main \
  -X faulthandler -c "import faulthandler; faulthandler.dump_traceback_later(60); import open_webui.main; print('IMPORT OK')"

IMPORT OK means imports are fine and the problem is elsewhere; a stack trace after ~60s names the exact import that is blocking.


Startup stops after the banner while Hugging Face is slow or blocked​

Symptom​

The log prints the Open WebUI banner and then nothing new for minutes. Application startup complete. does not appear and the page does not load. It happens when the server cannot reach Hugging Face quickly, for example behind a corporate proxy or firewall, or with no internet access.

Cause​

With the Default (SentenceTransformers) embedding engine, every start loads the local embedding model (RAG_EMBEDDING_MODEL, sentence-transformers/all-MiniLM-L6-v2 by default) before the server accepts connections. While RAG_EMBEDDING_MODEL_AUTO_UPDATE is True, its default, that step contacts Hugging Face to check the model and download missing files, even when a copy is already cached. Startup waits until the request finishes or fails. When hybrid search is on, the reranking model goes through the same step under RAG_RERANKING_MODEL_AUTO_UPDATE. If the model is not cached and the request fails, the log shows Cannot determine model snapshot path.

Fix​

Pick one:

  • Skip the check once the model is cached. Set RAG_EMBEDDING_MODEL_AUTO_UPDATE=false. Open WebUI then loads the cached copy without contacting Hugging Face. If the model is not cached yet, it logs Cannot determine model snapshot path and loads the model by its Hugging Face name, so the first start still needs the network.
  • Go fully offline. Set OFFLINE_MODE=true, which also sets HF_HUB_OFFLINE=1 and turns off both auto-update variables. The model must already be cached, see the next section.
  • Send the download through your proxy. The Hugging Face client reads the standard proxy variables HTTPS_PROXY (or https_proxy) and NO_PROXY from the environment of the Open WebUI process. Set them where you set the other Open WebUI variables, such as -e for docker run or an export in the shell.
  • Use an external embedding engine. Set Embedding Model Engine in Settings > Documents (admin section) to Ollama, OpenAI or Azure OpenAI, or set RAG_EMBEDDING_ENGINE. No local embedding model loads at startup then.

ValueError: No embedding model is loaded with offline mode on a fresh install​

Symptom​

The container starts, its log carries the LocalEntryNotFoundError below, and the first document upload or RAG query then fails with the ValueError:

huggingface_hub.errors.LocalEntryNotFoundError: Cannot find an appropriate cached
snapshot folder ... outgoing traffic has been disabled.

ValueError: No embedding model is loaded. Set RAG_EMBEDDING_MODEL to a valid
SentenceTransformer model name, or configure an external RAG_EMBEDDING_ENGINE
(ollama, openai, azure_openai).

It happens when OFFLINE_MODE=true and/or HF_HUB_OFFLINE=1 are set on a fresh install.

Cause​

Offline mode blocks the Hugging Face downloads and the version check. The default RAG embedding engine uses a local SentenceTransformers model that must be downloaded once. On a fresh install with offline mode already enabled, it was never cached, so there is nothing to load. The error surfaces on the first embedding call.

Fix​

Pick one:

  • Cache it first. Boot once without OFFLINE_MODE / HF_HUB_OFFLINE so the embedding model downloads and caches, then re-enable offline mode for subsequent runs.
  • Use an external embedder so nothing needs downloading: set RAG_EMBEDDING_ENGINE to ollama (with a pulled RAG_EMBEDDING_MODEL), openai, or azure_openai.
  • Pre-bake or mount the model cache into the image/volume for air-gapped deployments.

See the Offline Mode guide for the full offline setup.


WEBUI_SECRET_KEY is not set on a fresh Windows install​

Symptom​

backend\start_windows.bat aborts at startup:

WEBUI_SECRET_KEY is not set. It is a hard requirement when authentication is enabled.

Cause​

The script reads the key from .webui_secret_key and generates one only when that file does not exist. An empty .webui_secret_key, left behind by an earlier failed run, is read as an empty key.

Fix​

Delete the empty .webui_secret_key file from the backend folder and start again, so the script generates a key.

Setting WEBUI_SECRET_KEY yourself also works, and is the right configuration for anything beyond a personal machine. With it set, the script skips key generation entirely.

See WEBUI_SECRET_KEY for how each start method generates and persists the key.


Could not parse SQLAlchemy URL from given URL string at startup​

Symptom​

Open WebUI stops while loading, and the traceback ends with:

sqlalchemy.exc.ArgumentError: Could not parse SQLAlchemy URL from given URL string

Cause​

DATABASE_URL is set to an empty value, such as a DATABASE_URL= line with nothing after the equals sign. Open WebUI uses its SQLite default only when the variable is not set at all, so the empty value is passed on as the database URL. A DATABASE_URL left in your shell from another project also replaces the default, and Open WebUI then connects to that project's database.

Fix​

Remove or unset DATABASE_URL (unset DATABASE_URL in the shell you start Open WebUI from) to use the SQLite database in DATA_DIR, or set it to a full URL. See DATABASE_URL.


A Function stops Open WebUI loading​

Symptom​

Open WebUI does not start, or its interface does not load, after you added or updated a Function.

Fix​

  1. Restart Open WebUI with SAFE_MODE=true. At startup it turns off every Function in the database, so none of them load.
  2. Open Admin Panel > Functions and delete or fix the Function that caused the problem.
  3. Remove SAFE_MODE and restart. While it is set, every restart turns all Functions off again.
  4. Turn each Function you still need back on in Admin Panel > Functions. Removing SAFE_MODE does not turn them back on.

See Safe Mode.

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.