Error messages

Open WebUI Backend Required

Open WebUI Backend Required

The page goes blank apart from a heading and a Check Again button:

Open WebUI Backend Required

Oops! You're using an unsupported method (frontend only). Please serve the WebUI from the backend.

We read the code behind it in Open WebUI 0.11.4. When the app starts in your browser, it makes one request to /api/config on the same address the page came from. If that request fails for any reason (the connection is refused, the server answers with an error status, or the answer isn't JSON), the app sends you to its /error page, which is this screen. The words "frontend only" date from when the likeliest cause was someone running the interface's development server without the Python backend. Open WebUI's connection troubleshooting page says the error "does not mean you are running a frontend-only build".

The heading is built from the app's name, which only comes from the backend config. Since that's the thing that didn't load, the default name stays, so you see "Open WebUI" even on an instance that's been renamed.

What the failed request tells you

The official Docker image runs one process that serves both the interface and the API on container port 8080. A maintainer put it this way in issue #25968: the message "means the page loaded but its request to /api/config (same origin) failed." If the page reached you, the API should be right behind it, so something between the two is off.

The quickest test is the maintainer's own. Fetch the config from the machine where your browser runs, using the exact host and port in your address bar:

curl http://localhost:3001/api/config

JSON coming back means the backend is reachable and your browser is the problem. An empty reply or a refused connection means the route to the backend is broken.

When curl fails: port, tunnel or proxy

The docs list what to check. Each container should map its host port to container port 8080, as in ports: ["3001:8080"]. If you reach it over an SSH tunnel, the tunnel has to forward to the port that instance actually publishes, which is easy to get wrong once there's a second instance (that was the setup in #25968).

Behind a reverse proxy such as Traefik or nginx, the proxy has to send /api to the same backend as the page. In a 2024 discussion about Traefik, one user traced the screen to the config request and wrote that it happens "when you are redirecting /api to the wrong adress". The 0.11.4 code also has a special case for login proxies like Authentik: if the config request fails because the proxy redirected it to a login page, the app reloads so the browser can follow the redirect, instead of showing this screen.

When curl works: a cached page

If the API answers and the browser still shows the error, the docs point at a stale copy of the page. Open WebUI 0.11.4 registers no service worker (a script a site leaves in your browser to serve pages offline), and it unregisters any it finds when it loads. A cached shell can still come from the browser's HTTP cache, or from a worker another app left on the same address. A hard refresh doesn't remove a service worker. Unregister it in DevTools under Application, then Service Workers, or open the address in a private window. People in that same discussion fixed theirs by clearing the site's data, and one found a browser userscript (a video downloader) was breaking it.

When the backend never started

The other cause is a server that isn't running at all, which you'll see in its logs rather than the browser. In issue #21945, upgrading from 0.7.2 to 0.8.x stopped a database migration halfway, and the log read Error running migrations: (sqlite3.OperationalError) table chat_message already exists. From 0.8.2 on, that setup showed "Open WebUI Backend Required" in the browser. The maintainer's answer was the manual database migration guide, which covers "table already exists" and "no such table" and says to back up the database first. Run docker logs on the container before touching the network.

If you're running the development setup (the interface on port 5173 and the backend separately), both halves have to be up. In 0.6.17 the backend's dev.sh set CORS_ALLOW_ORIGIN with a trailing slash, which blocked the browser's request; a maintainer confirmed it was fixed on the dev branch.

If the backend is up but it's Ollama or your API provider that can't be reached, that's a different message: see “Open WebUI: Server Connection Error”.