Skip to main content

Troubleshooting

Start with the layer that is failing: browser, frontend, backend, Ollama, provider plugin, or deployment networking.

Quick Checks​

# App branch and local changes
git status

# Backend health
curl http://localhost:3001/api/health

# Ollama health
curl http://localhost:11434/api/tags

# Installed Ollama models
ollama list

In development, the frontend usually runs on http://localhost:5173 and the backend on http://localhost:3001. The packaged npx libre-webui flow serves the app on http://localhost:8080.

Libre WebUI Does Not Start​

Check Node and dependencies

node --version
npm install
npm run dev

Node.js 22.22 or newer is required.

Port already in use

lsof -i :3001
lsof -i :5173
lsof -i :8080

Stop the old process or configure another port.

Backend cannot write data

The backend stores data under DATA_DIR when set, otherwise under backend/data from the project root. Make sure that directory is writable.

Browser Cannot Reach the Backend​

For local development, the frontend uses VITE_API_BASE_URL when set and otherwise falls back to the development backend.

Frontend .env example:

VITE_API_BASE_URL=http://localhost:3001/api
VITE_WS_BASE_URL=ws://localhost:3001

Backend .env example:

CORS_ORIGIN=http://localhost:5173,http://127.0.0.1:5173

For phone, LAN, or Tailscale access, do not point the phone browser at localhost; use the laptop’s LAN or Tailscale IP and run the dev server with host binding:

npm run dev:host

Ollama Is Not Detected​

Confirm Ollama is running

curl http://localhost:11434/api/tags

Configure a custom Ollama URL

Backend .env:

OLLAMA_BASE_URL=http://localhost:11434

If Libre WebUI runs in Docker and Ollama runs on the host, use the external Ollama compose file or point OLLAMA_BASE_URL at the host address reachable from the container.

Model Pull Problems​

Pull from terminal first

ollama pull gemma3:4b

If the terminal pull fails, the problem is outside Libre WebUI.

Cloud models

Use the cloud filter in the Model Manager for Ollama Cloud models. Libre WebUI normalizes required cloud suffixes from that flow, so users should not need to manually add :cloud for supported cloud entries.

User cannot pull models

Administrators can disable model pulls for normal users. Check admin settings if a non-admin user can browse models but cannot install them.

Chat Is Slow or Fails​

  • Use a smaller model.
  • Check loaded models with ollama ps.
  • Reduce context length.
  • Reduce max tokens for very long responses.
  • Confirm the model fits in RAM/VRAM.
  • For provider plugins, confirm the API key and provider quota.

Work Problems​

Work Is Missing or Reports Runtime Unavailable​

Work requires a currently authenticated administrator. Its container runtime must be available to the Libre WebUI backend:

docker info
docker version

Confirm Docker is running and that the operating-system user running the backend can invoke the configured WORK_DOCKER_COMMAND. Installing Libre WebUI with npx does not install Docker. If Docker is missing, Libre WebUI keeps the rest of the application available and does not fall back to executing model commands on the host.

The standard Compose image and current Helm chart do not provide a Work runtime by default. The application container has neither the Docker CLI nor the host Docker socket. Mounting /var/run/docker.sock into a web application grants root-equivalent control of the Docker host; review Work: Isolated Workspaces before designing a custom deployment.

The Model Lacks Tool Support​

Work requires a tool-capable chat model. For Ollama, choose an installed model whose reported capabilities include tools. For a plugin-backed model:

  • Confirm the chat or completion plugin is active.
  • Confirm the selected model is in that plugin's configured model list.
  • Confirm an API key is available for the current administrator.
  • Confirm the provider supports tool calls for that exact model.

Libre WebUI does not silently route a failed Work run to a different provider.

A Work Request Returns HTTP 429​

The instance has reached a task or active-runtime admission limit. By default, Libre WebUI allows two active container-backed tasks across the instance and one per user. A running preview also occupies runtime capacity. Wait for the other operation to finish, stop an unused preview, or have the operator review the WORK_MAX_ACTIVE_RUNTIMES_* and WORK_MAX_TASKS_* settings.

Package Installation or Network Access Fails​

New Work tasks use Docker bridge networking so generated projects can download packages and start previews. Check Docker DNS, proxy configuration, registry availability, and the command output in Activity. Libre WebUI does not mount host SSH keys, cloud credentials, browser profiles, or the Docker socket into the task container.

A Work Preview Does Not Start​

  • Make sure the server binds to 0.0.0.0 on WORK_PREVIEW_PORT (4173 by default).
  • Leave the optional command empty to auto-detect a package.json dev script or a plain index.html, including a single nested app.
  • If Work reports multiple apps or no supported entry point, enter the project's explicit development command in the optional command field. The command starts in /workspace, so use cd <app-directory> && ... for a nested app.
  • Expand the returned error details to inspect startup output.
  • Stop an existing preview before starting another command that needs the container.

Preview URLs use a dynamically assigned loopback port. The browser and Libre WebUI backend therefore need to run on the same machine. A browser connected to a remote backend cannot reach that backend's loopback preview, and an HTTPS page may block a plain-HTTP preview as mixed content.

A Workspace File Cannot Be Opened or Saved​

The Work file API accepts UTF-8 text files up to 2 MB. If a file changed after you opened it, reload it before saving so you do not overwrite the newer version. Formatting is limited to supported file types under 100,000 characters and 4,000 lines; syntax highlighting pauses for large files to keep editing responsive.

Unsaved edits are kept as a draft in the current browser. They are not a substitute for saving to the persistent workspace.

A Task or Preview Was Stopped​

Stopping a run, stopping a preview, or restarting Libre WebUI stops disposable container processes but preserves the task's named workspace volume. Reopen the task and restart its preview. Deleting the task is different: after confirmation, it permanently removes the task and its workspace.

Login and Signup Problems​

First user is not admin

Only the first account created in a fresh database becomes admin. Existing databases keep their current users and roles.

JWT errors

Set a stable secret in production:

JWT_SECRET=replace-with-a-long-random-secret

Changing JWT_SECRET invalidates existing sessions.

Turnstile blocks signup

Turnstile is enabled only when both keys are present:

TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...

If signup suddenly fails, confirm the site key matches the domain and the secret key is valid.

OAuth redirects fail

Set callback URLs in both the provider dashboard and backend .env:

BASE_URL=https://your-domain.example
GITHUB_CALLBACK_URL=https://your-domain.example/api/auth/oauth/github/callback
HUGGINGFACE_CALLBACK_URL=https://your-domain.example/api/auth/oauth/huggingface/callback

Document Chat Problems​

Libre WebUI currently accepts PDF and plain-text files up to 10 MB.

If search works but semantic retrieval does not:

  1. Install an embedding model such as nomic-embed-text.
  2. Enable embeddings in Settings.
  3. Regenerate embeddings from the document settings or API.
ollama pull nomic-embed-text

Keyword search continues to work when embeddings are disabled.

Artifact Preview Problems​

For games or interactive HTML, ask the model for one complete self-contained HTML file with inline CSS and JavaScript.

If the artifact needs keyboard input:

  • Click inside the preview first.
  • Use the Open button to run it in its own browser tab.
  • Avoid relying on local files that were not included in the response.

Libre WebUI can bundle common index.html + CSS + JavaScript code blocks, but self-contained HTML is still the most reliable output.

Docker Problems​

Container cannot reach Ollama

Use the external Ollama compose file when Ollama is not in the same compose stack:

docker compose -f docker-compose.external-ollama.yml up -d

Data does not persist

Mount a persistent data volume and set DATA_DIR if needed. The encryption key is stored in persistent storage when DATA_DIR or Docker mode is used.

Resetting Local Data​

Stop the app first. Then back up and remove the data directory you are using. By default, development data lives under backend/data.

cp -R backend/data backend/data.backup
rm -rf backend/data

Restart the backend and create a fresh account.

Still Stuck​

Open an issue with:

  • Libre WebUI version and commit
  • Install method
  • Operating system
  • Node.js version
  • Ollama version
  • Docker version and docker info result for Work problems
  • Backend logs around the failure
  • Browser console errors
  • The exact model or provider being used
  • Work Activity output when a task or preview fails