Problemen oplossen

Begin bij de falende laag: browser, frontend, backend, Ollama, providerplugin of netwerk.

Snelle controles

# App branch and local changes
git status

# Backend process liveness
curl http://localhost:3001/health/live

# Backend dependency readiness (SQLite, schema, and writable data storage)
curl http://localhost:3001/health/ready

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

# Installed Ollama models
ollama list

Frontend meestal http://localhost:5173, backend http://localhost:3001; npx libre-webui gebruikt http://localhost:8080.

Libre WebUI start niet

node --version
npm install
npm run dev

Node.js 22.22 of nieuwer.

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

Stop oud proces of wijzig poort.

Backend kan niet schrijven

Gebruikt DATA_DIR of backend/data. Source resolveert relatief vanaf backend: DATA_DIR=./data → backend/data, DATA_DIR=./backend/data → backend/backend/data. Controleer rechten. Zonder waarde behoudt Libre historische map als enige store. Als beide data hebben, stop en maak back-up; geen automatische merge/kopie.

Health:

• /health, /health/live: 200 als HTTP leeft, provider niet relevant.
• /health/ready: 503 bij verplichte database/schema/opslag/platformfout, zonder publieke details.
• /health/deep: SQLite-integriteit en optionele providerprobes; providerfout is waarschuwing. Vereist admin Bearer, niet voor frequente probe.

curl -H "Authorization: Bearer $LIBRE_ADMIN_TOKEN" \
  http://localhost:3001/health/deep

Browser bereikt backend niet

Controleer zowel de frontend-.env als de backend-.env.

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

VITE_API_BASE_URL wordt gebruikt wanneer ingesteld. VITE_WS_BASE_URL is gedeeld voor Chat/Work-terminal en moet absoluut ws:/wss: zijn; een prefix zoals wss://example.com/libre kan, zonder credentials/query/fragment. Herstart na Vite-wijziging.

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

Voor telefoon/LAN/Tailscale gebruik laptop-IP en:

npm run dev:host

Dit serveert de frontend op poort 8080 en proxyt API- en WebSocket-verkeer naar de lokale backend op poort 3001. Alleen poort 8080 hoeft bereikbaar te zijn vanaf het andere apparaat. Als VITE_API_BASE_URL of VITE_WS_BASE_URL is ingesteld in frontend/.env, zorg dan dat die URL's bereikbaar zijn vanaf het andere apparaat, of verwijder ze om de dev-server-proxy te gebruiken.

Chat streamt niet achter reverse proxy

Bericht verzendt, antwoord ontbreekt, WebSocket-fout. Controleer upgrades en lange verbindingen.

Met CORS_ORIGIN of BASE_URL moet browser-Origin overeenkomen. Stel remote minstens één in. Electron/non-browser kan Origin missen maar gebruikt kort ticket. Bescherm met TLS.

services:
  libre-webui:
    environment:
      CORS_ORIGIN: https://chat.example.com
      BASE_URL: https://chat.example.com

Proxy op Dockerhost gebruikt 8080; in Compose-netwerk libre-webui:3001.

nginx

location /ws {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;
}

Valideer met nginx -t.

Caddy

reverse_proxy ondersteunt WebSocket automatisch:

chat.example.com {
    reverse_proxy 127.0.0.1:8080
}

Traefik

labels:
  - 'traefik.enable=true'
  - 'traefik.http.routers.libre-webui.rule=Host(`chat.example.com`)'
  - 'traefik.http.routers.libre-webui.entrypoints=websecure'
  - 'traefik.http.routers.libre-webui.tls=true'
  - 'traefik.http.services.libre-webui.loadbalancer.server.port=3001'

Controleer idle timeout; in Traefik transport.respondingTimeouts.

Ollama niet gevonden

Een aangepaste URL wordt in backend-.env ingesteld.

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

OLLAMA_BASE_URL=http://localhost:11434

Bij Docker/host gebruik externe Compose of bereikbaar OLLAMA_BASE_URL.

Modeldownloadproblemen

ollama pull gemma4:12b

Terminalfout ligt buiten Libre. Gebruik cloudfilter voor Ollama Cloud; geen handmatige :cloud. Beheerder kan downloads blokkeren.

Chat traag of mislukt

Kleiner model, ollama ps, minder context/tokens, controleer RAM/VRAM en providerkey/quota.

OpenAI-afbeeldingen niet beschikbaar

• Activeer OpenAI; gebruikerssleutel of OPENAI_API_KEY.
• Schakel afbeeldingen in en kies GPT Image.
• Gebruik gpt-image-2; oude IDs zijn deprecated.
• Laat image_endpoint leeg behalve compatibele API; /responses//chat/completions zijn geen Image API.
• Controleer organisatiegerechtigdheid.

Beschikbaarheid is per huidige gebruiker.

Problemen met providerendpoints

Controleer Instellingen → Plugins:

• Chat Completions voor /chat/completions, Responses voor /responses.
• Base URL als root https://provider.example/v1.
• API Path leeg of slashpad.
• Echt custom legacy endpoint heeft hoogste prioriteit; wis bij terugkeer. Bekende suffix bepaalt payload.

Geïmporteerde JSON ondersteunt OpenAI Chat Completions, Responses, Anthropic en Gemini. Proprietair protocol vereist adapter.

HTTP versleutelt niet. Base URL geen query/fragment; relatieve paden geen traversal/query/fragment of overmatige encoding.

Modelrefresh vervangt bekende suffix door /models; gebruikt huidige gebruiker. Sleutel opslaan/verwijderen en route reset vernieuwt, generatie niet. IDs per gebruiker. Zonder compatibele route gebruik model_map.

Providerrequests volgen geen redirects. Configureer eindbestemming. Work stopt bij routewijziging vóór volgende aanvraag.

Aanvragen komen uit backend; localhost in container is container. Gebruik http://ai-gateway:8080/v1 of, indien beschikbaar, http://host.docker.internal:8080/v1. HTTP blijft plaintext.

Regels:

• Alleen admin wijzigt routing; gewone gebruikers generatie, sleutel, activatie.
• endpoint/api_url is volledige URL zoals https://provider.example/v1/chat/completions; root alleen base_url met api_mode/api_path.
• Alleen absolute HTTP(S); leeg erft, fout geweigerd.
• Omgevingssleutel alleen voor ongewijzigd ingebouwd manifest. Import/custom vereist accountsleutel.
• Oude customdefinitie opnieuw importeren; directe wijziging quarantaint.
• Sleutels gebonden aan route/contract/definitie/bron en opnieuw opslaan na wijziging.
• api_url alias, endpoint wint; models_endpoint voor lijst.
• Activeer na route/sleutel; activering leidt /models af en wacht. Per account.
• Modellen vernieuwen toont read-only catalogus; tijdelijke fout houdt vorige of model_map.
• Discovery verwacht data; routewijziging wist oude catalogus.
• Afbeeldingen per gebruiker.
• Reset oude niet-adminroute.
• Geen redirects.

Chat gebruikt verkeerde of onbeschikbare provider

Zelfde ID kan bij Ollama/plugins bestaan; huidige sessies bewaren provider + raw ID.

• Heractiveer exact plugin en controleer map.
• Kies expliciet vervanging.
• Legacy zonder metadata blijft naamrouting en toont "provider niet vastgelegd"; herselecteer.
• Persona's blijven persona:<id>; nieuwe zijn Ollama-backed.

Work-problemen

Compose-gerelateerde waarden worden in .env opgeslagen.

Work ontbreekt of runtime onbeschikbaar

Vereist aangemeld account met Work-toegang en bereikbare runtime:

docker info
docker version

Controleer Docker en WORK_DOCKER_COMMAND. npx installeert Docker niet. Zonder runtime blijft app werken en voert niets op host uit.

Compose monteert socket; Kubernetes gebruikt work.enabled=true, nooit nodesocket.

Bericht	Oplossing
The "docker" CLI is not installed…	Gebruik officiële image, installeer docker-cli of stel WORK_DOCKER_COMMAND in
No Docker daemon is reachable…	Herstel mount/start Docker
The Docker socket is mounted but…cannot open	Stel DOCKER_GID in
Work-scherm of -audio sluit met WebSocket 1006 en logt screen is unreachable	De backend in de container belt zijn eigen loopback. Gebruik op Docker Desktop de meegeleverde WORK_DOCKER_PUBLISHED_HOST=host.docker.internal; stel op native Docker Engine ook WORK_PREVIEW_BIND in op de niet-publieke gateway van de Docker-bridge en maak Libre WebUI opnieuw aan

echo "DOCKER_GID=$(docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  alpine stat -c '%g' /var/run/docker.sock)" >> .env
docker compose up -d --force-recreate

Socket is root-equivalent. Zie Work.

Model mist tools

Kies Ollama met tools; bij plugin controleer actief, model, adminsleutel en toolsupport. Geen fallback.

HTTP 429

Taak-/runtimelimiet bereikt. Standaard twee instantie en één gebruiker; preview telt. Wacht, stop of wijzig WORK_MAX_ACTIVE_RUNTIMES_*/WORK_MAX_TASKS_*.

Pakketten/netwerk mislukt

Controleer Docker DNS, proxy, registry en Activiteit. Geen host-SSH, cloudcredentials, browserprofiel of socket in taak.

Preview start niet

• Luister 0.0.0.0 op WORK_PREVIEW_PORT (standaard 4173).
• Leeg commando detecteert package.json dev of index.html.
• Bij meerdere/geen app geef commando, vanaf /workspace; cd <app-directory> && ....
• Bekijk details en stop bestaande preview.

Preview is dynamische loopback. Remote browser bereikt dit niet; HTTPS kan HTTP mixed content blokkeren.

Bestand opent/slaat niet op

UTF-8 tot 2 MB. Herlaad bij wijziging. Formattering onder 100.000 tekens/4.000 regels; highlighting pauzeert. Browserconcept is geen opslag.

Taak/preview gestopt

Stop/restart verwijdert processen maar bewaart volume. Verwijderen wist taak/ruimte permanent.

Aanmeld- en registratieproblemen

OAuth-callbacks worden in backend-.env ingesteld.

Eerste account in nieuwe database is admin; bestaande rollen blijven.

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

JWT_SECRET wijzigen maakt sessies ongeldig.

TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...

Beide nodig; controleer domein/geheim.

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

Documentchatproblemen

PDF, Office, Markdown, HTML, code en CSV tot 10 MB. Voor semantisch:

1. Installeer nomic-embed-text.
2. Activeer embeddings.
3. Regenereer.

ollama pull nomic-embed-text

Trefwoord blijft werken.

Artefactpreviewproblemen

Vraag één volledig HTML-bestand met inline CSS/JS. Klik voor toetsenbord, open eigen tabblad, vermijd ontbrekende lokale bestanden. Bundeling kan, standalone betrouwbaarder.

Dockerproblemen

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

Voor persistentie mount volume en stel DATA_DIR in; sleutel blijft bij data.

Lokale data resetten

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

Stop eerst, herstart en maak account.

Nog vast

Open issue met versie/commit, installatiemethode, OS, Node.js, Ollama, Docker+docker info, backendlogs, browserconsole, exact model/provider en Work-activiteit.