[GH-ISSUE #1309] Docs: add troubleshooting entries for two Docker startup failure modes (from #26163) #160

New issue

Closed

opened 2026-10-18 14:09:31 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-18 14:09:31 +00:00

Owner

Originally created by @Classic298 on GitHub (Jun 28, 2026).
Original GitHub issue: https://github.com/open-webui/docs/issues/1309

Two distinct, real-world startup failures surfaced in #26163 that aren't currently
covered in the troubleshooting docs. Both are setup/config issues, but each cost
significant back-and-forth to diagnose. Proposing two short troubleshooting entries.

1. Container hangs at startup on Apple Silicon (emulated amd64 image)

Symptom

On macOS Apple Silicon (M1/M2/M3), the container freezes during startup after
migrations complete, right after:
WARNING: CORS_ALLOW_ORIGIN IS SET TO '*' - NOT RECOMMENDED ...
No banner, no Started server process, no error. Hangs indefinitely (confirmed
still dead after 1h). Reproduces on a brand-new empty data volume.
OFFLINE_MODE / HF_HUB_OFFLINE make no difference.

Root cause

The host had DOCKER_DEFAULT_PLATFORM=linux/amd64 set globally, so Docker pulled
the x86_64 image and ran it under Rosetta emulation on an ARM host. A native
extension wedges during import under emulation.

Fix / what to document

On Apple Silicon, run the native arm64 image — let Docker auto-select the arch,
or force it: docker run --platform linux/arm64 ...
Check for a global override: echo $DOCKER_DEFAULT_PLATFORM (and Docker Desktop
settings). Unset it or override per-run.
Confirm the running arch: docker run --rm ghcr.io/open-webui/open-webui:<tag> uname -m
(should be aarch64 on Apple Silicon).
Note explicitly: running x86 images under emulation on Apple Silicon is not
supported / best-effort and can hang at startup.

2. `ValueError: No embedding model is loaded` when OFFLINE_MODE is set on a fresh install

Symptom

Startup fails with:

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).

Occurs when OFFLINE_MODE=true and/or HF_HUB_OFFLINE=1 are set.

Root cause

Offline mode means "never reach the network." The default RAG embedding engine uses
a local SentenceTransformers model that must be downloaded once. On a fresh
install with offline mode enabled, it was never cached, so there's nothing to load.

Fix / what to document

First boot without OFFLINE_MODE / HF_HUB_OFFLINE so the embedding model is
downloaded and cached, then re-enable offline mode for subsequent runs; or
Use an external embedder so nothing needs downloading:
RAG_EMBEDDING_ENGINE=ollama (with a pulled RAG_EMBEDDING_MODEL), or openai /
azure_openai; or
Pre-bake/mount the model cache into the image/volume for air-gapped deployments.
Cross-link from the OFFLINE_MODE and RAG embedding env-var docs.

Suggested placement

Troubleshooting section, under Docker / startup issues.
Add a one-line note to the OFFLINE_MODE env-var reference pointing at entry #2.

Source: https://github.com/open-webui/open-webui/issues/26163

Originally created by @Classic298 on GitHub (Jun 28, 2026). Original GitHub issue: https://github.com/open-webui/docs/issues/1309 Two distinct, real-world startup failures surfaced in #26163 that aren't currently covered in the troubleshooting docs. Both are setup/config issues, but each cost significant back-and-forth to diagnose. Proposing two short troubleshooting entries. ### 1. Container hangs at startup on Apple Silicon (emulated amd64 image) **Symptom** - On macOS Apple Silicon (M1/M2/M3), the container freezes during startup after migrations complete, right after: `WARNING: CORS_ALLOW_ORIGIN IS SET TO '*' - NOT RECOMMENDED ...` - No banner, no `Started server process`, no error. Hangs indefinitely (confirmed still dead after 1h). Reproduces on a brand-new empty data volume. - `OFFLINE_MODE` / `HF_HUB_OFFLINE` make no difference. **Root cause** - The host had `DOCKER_DEFAULT_PLATFORM=linux/amd64` set globally, so Docker pulled the **x86_64 image and ran it under Rosetta emulation** on an ARM host. A native extension wedges during import under emulation. **Fix / what to document** - On Apple Silicon, run the **native arm64 image** — let Docker auto-select the arch, or force it: `docker run --platform linux/arm64 ...` - Check for a global override: `echo $DOCKER_DEFAULT_PLATFORM` (and Docker Desktop settings). Unset it or override per-run. - Confirm the running arch: `docker run --rm ghcr.io/open-webui/open-webui:<tag> uname -m` (should be `aarch64` on Apple Silicon). - Note explicitly: running x86 images under emulation on Apple Silicon is **not supported / best-effort** and can hang at startup. ### 2. `ValueError: No embedding model is loaded` when OFFLINE_MODE is set on a fresh install **Symptom** - Startup fails with: ``` 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). ``` - Occurs when `OFFLINE_MODE=true` and/or `HF_HUB_OFFLINE=1` are set. **Root cause** - Offline mode means "never reach the network." The default RAG embedding engine uses a **local SentenceTransformers model that must be downloaded once**. On a fresh install with offline mode enabled, it was never cached, so there's nothing to load. **Fix / what to document** - First boot **without** `OFFLINE_MODE` / `HF_HUB_OFFLINE` so the embedding model is downloaded and cached, then re-enable offline mode for subsequent runs; **or** - Use an external embedder so nothing needs downloading: `RAG_EMBEDDING_ENGINE=ollama` (with a pulled `RAG_EMBEDDING_MODEL`), or `openai` / `azure_openai`; **or** - Pre-bake/mount the model cache into the image/volume for air-gapped deployments. - Cross-link from the OFFLINE_MODE and RAG embedding env-var docs. ### Suggested placement - Troubleshooting section, under Docker / startup issues. - Add a one-line note to the `OFFLINE_MODE` env-var reference pointing at entry #2. Source: https://github.com/open-webui/open-webui/issues/26163

bsakaguchi closed this issue

2026-10-18 14:09:32 +00:00

bsakaguchi referenced this issue

2026-10-18 14:10:52 +00:00

[PR #160] [MERGED] fixed mismatched header size (3 to 4) for ENABLE_LOGIN_FORM #290