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.
Opgeslagen referenties zijn gebonden aan de route, het authenticatiecontract, de definitie en de bron die golden toen ze werden ingevoerd. Modellen toevoegen of verwijderen behoudt ze. Sla na het wijzigen van een endpoint of een ander deel van de definitie de referentie van dat account opnieuw op. Een oude ongebonden referentie migreert alleen automatisch op een exact verankerde meegeleverde route.
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:

Installeer nomic-embed-text.
Activeer embeddings.
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.

Problemen met de Strands-engine

De ingebouwde Strands-engine meldt zijn status aan elk account dat hem mag gebruiken:

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

Een 403-antwoord betekent dat de engine niet is ingeschakeld voor dat account.

De Strands-pagina ontbreekt

De zijbalk verbergt Strands als het account geen toegang heeft. Controleer Instellingen → Gebruikersbeheer → Toegang en beleid → Strands-engine. Uit blokkeert iedereen, ook beheerders, en Beheerders verbergt de pagina voor gewone gebruikers. Is het besturingselement vergrendeld, dan legt LIBRE_STRANDS_ACCESS de modus vast: stel de variabele in op admins of all-users, of verwijder hem om de modus in de interface te beheren. Elke andere waarde dan disabled, admins of all-users zet de engine vergrendeld uit.

Er worden geen modellen weergegeven

Strands stuurt alleen modellen aan die Libre WebUI al aanbiedt. Schakel Ollama in en haal een chatmodel op, of activeer een chat-providerplugin onder Instellingen → Plugins. De modellenlijst van Strands bevat daarna die modellen.

Een Work-stap op Strands mislukt omdat tools niet worden ondersteund

Met Engine: Strands plant de Strands-agent elke stap via toolaanroepen, dus het providermodel moet toolaanroepen ondersteunen. Doet het dat niet, dan meldt Work dat het model geen toolondersteuning aangeeft (WORK_MODEL_TOOLS_UNSUPPORTED). Kies een model met toolondersteuning in het Work-besturingselement Model en voer de taak opnieuw uit.

Nog vast

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

Snelle controles​

Libre WebUI start niet​

Browser bereikt backend niet​

Chat streamt niet achter reverse proxy​

nginx​

Caddy​

Traefik​

Ollama niet gevonden​

Modeldownloadproblemen​

Chat traag of mislukt​

OpenAI-afbeeldingen niet beschikbaar​

Problemen met providerendpoints​

Chat gebruikt verkeerde of onbeschikbare provider​

Work-problemen​

Work ontbreekt of runtime onbeschikbaar​

Model mist tools​

HTTP 429​

Pakketten/netwerk mislukt​

Preview start niet​

Bestand opent/slaat niet op​

Taak/preview gestopt​

Aanmeld- en registratieproblemen​

Documentchatproblemen​

Artefactpreviewproblemen​

Dockerproblemen​

Lokale data resetten​

Problemen met de Strands-engine​

De Strands-pagina ontbreekt​

Er worden geen modellen weergegeven​

Een Work-stap op Strands mislukt omdat tools niet worden ondersteund​

Nog vast​