Depanare

Începeți cu nivelul care eșuează: browser, frontend, backend, Ollama, pluginul furnizorului sau rețeaua deployment-ului.

Verificări rapide

# 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

În dezvoltare, frontend-ul rulează de obicei la http://localhost:5173, iar backend-ul la http://localhost:3001. Fluxul împachetat npx libre-webui servește aplicația la http://localhost:8080.

Libre WebUI nu pornește

Verificați Node și dependențele

node --version
npm install
npm run dev

Este necesar Node.js 22.22 sau mai nou.

Portul este deja folosit

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

Opriți procesul vechi sau configurați alt port.

Backend-ul nu poate scrie datele

Backend-ul stochează date în DATA_DIR când acesta este setat, altfel în backend/data. La pornirea din source, un DATA_DIR relativ este rezolvat din directorul backend, nu din directorul curent al shell-ului. Astfel, DATA_DIR=./data selectează backend/data, iar valoarea acceptată istoric DATA_DIR=./backend/data selectează backend/backend/data. Directorul ales trebuie să poată fi scris. Fără o valoare, Libre păstrează directorul istoric dacă este singura stocare existentă. Dacă ambele locații conțin date, opriți Libre, faceți backup pentru ambele și alegeți sau migrați intenționat; Libre nu combină și nu copiază niciodată baze de date divergente.

Endpoint-urile health separă intenționat un proces activ de o aplicație utilizabilă:

• /health și /health/live returnează 200 cât timp backend-ul poate servi HTTP. Furnizorii opționali nu afectează liveness.
• /health/ready returnează 503 când o bază, schemă, stocare sau dependență de platformă obligatorie nu este disponibilă. Nu așteaptă furnizorii opționali, iar răspunsul public omite erorile și detaliile interne.
• /health/deep verifică integritatea SQLite și foreign keys într-un worker limitat și agregă probe opționale la nivel de server, precum Ollama. O pană a unui furnizor opțional apare ca avertisment și nu face dependențele obligatorii indisponibile. Endpoint-ul necesită un bearer token curent de administrator și nu este potrivit ca probă frecventă a orchestratorului.

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

Browserul nu poate accesa backend-ul

Pentru dezvoltarea locală, frontend-ul folosește VITE_API_BASE_URL când este setat, altfel revine la backend-ul de dezvoltare.

Exemplu de .env pentru frontend:

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

VITE_WS_BASE_URL este opțional, dar când este setat devine baza comună pentru socket-urile Chat și terminal Work. Folosiți un URL absolut ws: sau wss:; este acceptat și un prefix precum wss://example.com/libre. Nu includeți credentials, parametri query sau fragmente. Reporniți/reconstruiți frontend-ul după schimbarea unei variabile Vite.

Exemplu de .env pentru backend:

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

Pentru acces de pe telefon, LAN sau Tailscale, nu trimiteți browserul telefonului la localhost; folosiți IP-ul LAN/Tailscale al laptopului și porniți serverul dev cu host binding:

npm run dev:host

Acest lucru servește frontend-ul pe portul 8080 și direcționează traficul API și WebSocket către backend-ul local de pe portul 3001. Doar portul 8080 trebuie să fie accesibil de pe celălalt dispozitiv. Dacă VITE_API_BASE_URL sau VITE_WS_BASE_URL este setat în frontend/.env, asigurați-vă că acele URL-uri sunt accesibile de pe celălalt dispozitiv sau eliminați-le pentru a folosi proxy-ul serverului de dezvoltare.

Chat-ul nu transmite răspunsul prin reverse proxy

Simptomul obișnuit este că mesajul este trimis, dar răspunsul nu apare, iar consola browserului arată o eroare de conexiune WebSocket. Confirmați că proxy-ul permite upgrade-uri WebSocket și nu închide conexiunile de lungă durată.

Când este configurată oricare valoare, upgrade-urile browserului cu antet Origin sunt verificate față de CORS_ORIGIN și BASE_URL. Pentru un deployment la distanță, setați cel puțin una; fără ambele, filtrul Origin rămâne permisiv pentru dezvoltarea locală. Electron și alți clienți non-browser pot omite Origin, dar trebuie să schimbe mai întâi antetul Authorization pentru un ticket de scurtă durată și unică folosință. Păstrați backend-ul în spatele TLS și acelorași controale de rețea/reverse proxy ca API-ul HTTP.

Pentru un hostname public, permiteți originea browserului în serviciul Libre WebUI:

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

Exemplele nginx și Caddy presupun că proxy-ul rulează pe host-ul Docker, unde configurația Compose a repository-ului publică Libre WebUI pe portul 8080. Dacă proxy-ul intră în rețeaua Compose, folosiți libre-webui:3001 ca adresă upstream.

nginx

nginx necesită retransmiterea explicită a antetelor de upgrade. Timeout-ul mai lung păstrează deschisă o conexiune chat inactivă cât timp modelul lucrează.

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;
}

Reîncărcați nginx după validarea configurației cu nginx -t.

Caddy

reverse_proxy din Caddy acceptă WebSockets direct, fără antete de upgrade suplimentare:

chat.example.com {
    reverse_proxy 127.0.0.1:8080
}

Traefik

Traefik gestionează implicit upgrade-urile WebSocket. Când providerul Docker împarte rețeaua Libre WebUI, sunt necesare numai etichetele obișnuite pentru router și serviciu:

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'

Dacă stream-ul se conectează, dar cade ulterior, verificați timeout-ul de inactivitate al oricărui proxy sau load balancer din fața Traefik. Dacă Traefik impune limita, reglați transport.respondingTimeouts al entry point-ului.

Ollama nu este detectat

Confirmați că Ollama rulează

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

Configurați un URL Ollama personalizat

În .env al backend-ului:

OLLAMA_BASE_URL=http://localhost:11434

Dacă Libre WebUI rulează în Docker, iar Ollama pe host, folosiți fișierul Compose pentru Ollama extern sau setați OLLAMA_BASE_URL la adresa host-ului accesibilă din container.

Probleme la descărcarea modelelor

Încercați mai întâi din terminal

ollama pull gemma4:12b

Dacă descărcarea eșuează în terminal, problema este în afara Libre WebUI.

Modele cloud

Folosiți filtrul cloud din Model Manager pentru modelele Ollama Cloud. Libre WebUI normalizează sufixele obligatorii în acest flux, astfel încât utilizatorii nu trebuie să adauge manual :cloud pentru intrările acceptate.

Utilizatorul nu poate descărca modele

Administratorii pot dezactiva descărcarea modelelor pentru utilizatorii obișnuiți. Verificați setările de administrare dacă un utilizator poate vedea modelele, dar nu le poate instala.

Chat-ul este lent sau eșuează

• Folosiți un model mai mic, verificați modelele încărcate cu ollama ps, reduceți contextul și numărul maxim de tokeni.
• Confirmați că modelul încape în RAM/VRAM și, pentru pluginuri, verificați cheia API și cota furnizorului.

Generarea imaginilor OpenAI nu este disponibilă

• Activați furnizorul OpenAI inclus. Salvați o cheie API pentru utilizatorul curent sau configurați fallback-ul de mediu OPENAI_API_KEY al definiției incluse de încredere.
• Deschideți setările Image Generation, activați generarea și selectați unul dintre modelele GPT Image afișate.
• Preferați gpt-image-2. ID-urile GPT Image mai vechi rămân numai pentru compatibilitate și sunt deprecated upstream.
• Lăsați override-ul image_endpoint gol, dacă nu operați un endpoint compatibil. Un endpoint Chat /responses sau /chat/completions nu poate procesa cereri Image API.
• Dacă OpenAI respinge cererea în pofida unei chei și cote valide, confirmați eligibilitatea organizației API.

Disponibilitatea este evaluată cu credential-ul utilizatorului curent sau fallback-ul de mediu de încredere. Cheia altui utilizator nu expune modelele de imagine.

Probleme cu endpoint-ul furnizorului

Dacă un furnizor compatibil OpenAI primește calea greșită, verificați Settings → Plugins:

• Chat Completions pentru /chat/completions, Responses pentru /responses.
• O rădăcină API precum https://provider.example/v1 în Base URL.
• API Path gol pentru valoarea implicită sau o cale care începe cu slash.
• Un endpoint complet legacy are prioritate; ștergeți-l când reveniți la Base URL/API Path. Valorile implicite vechi ale manifestului sunt ignorate după upgrade. Sufixul /chat/completions sau /responses stabilește formatul cererii.

JSON-ul importat acceptă formatele wire OpenAI Chat Completions, Responses, Anthropic și Gemini. Un payload/stream/tool/response proprietar necesită un adaptor backend; schimbarea endpoint-ului nu traduce protocolul.

URL-urile pot folosi HTTP sau HTTPS. HTTP transmite credentials fără criptarea transportului și trebuie folosit numai cu un gateway self-hosted într-o rețea de încredere; preferați HTTPS cu TLS. Base URL nu poate conține query/fragment, iar API path relativ nu poate conține traversal, query, fragment sau codare repetată. Codarea excesivă instabilă este respinsă.

Refresh înlocuiește sufixuri cunoscute precum /responses cu /models. Activarea, actualizarea și override-urile folosesc endpoint-ul și cheia utilizatorului curent. Salvarea/eliminarea cheii și resetarea reîmprospătează catalogul; parametrii de generare fără legătură nu o fac. ID-urile sunt stocate per utilizator fără a suprascrie JSON-ul. Dacă ruta nu acceptă discovery, definiți ID-urile în model_map.

Cererile furnizorilor nu urmează redirect-uri pentru discovery, Chat, Work, imagini, embeddings sau TTS. Configurați URL-ul final. Închiderea sigură împiedică trimiterea antetului Authorization către o destinație nevalidată.

Dacă Work raportează schimbarea rutei în timpul execuției, porniți o execuție nouă după actualizare. Se oprește înaintea următoarei cereri către furnizor, astfel încât starea veche a instrumentelor să nu fie redată peste o altă limită de mode/endpoint/key.

Cererile pornesc din backend, deci localhost într-un container este containerul Libre. În Compose/Kubernetes, folosiți DNS-ul serviciului, de exemplu http://ai-gateway:8080/v1. Folosiți http://host.docker.internal:8080/v1 numai când serviciul este expus. HTTP rămâne plaintext și cu rezoluție privată.

Disponibilitatea modelelor de imagine, override-urile și cheile sunt rezolvate pentru utilizatorul curent. Dacă apar datele altui cont, verificați autentificarea cererii.

Se aplică și următoarele reguli de securitate și proprietate:

• Autentificați-vă ca administrator pentru rutare. Definițiile și câmpurile de conexiune sunt administrate la nivel de instanță, iar utilizatorii își salvează generarea, credentials și activarea.
• Pentru endpoint sau api_url legacy, introduceți URL-ul complet, cu operația, de exemplu https://provider.example/v1/chat/completions. Puneți rădăcina API numai în base_url, cu api_mode și un api_path opțional.
• Sunt acceptate URL-uri HTTP/HTTPS absolute. Folosiți HTTP numai pentru o rețea self-hosted de încredere, deoarece cheile, prompturile și răspunsurile nu au criptarea transportului.
• Un override gol folosește endpoint-ul inclus. O valoare explicită deformată sau nesigură este respinsă, fără fallback implicit.
• O cheie de mediu este folosită numai dacă definiția inclusă, neumbrită, păstrează rădăcina, câmpurile auth, endpoint-urile/selectoarele de capabilități și valorile implicite de rutare de încredere. Importurile, definițiile inscriptibile cu ID inclus și rutele personalizate de administrator necesită credential-ul aceluiași cont. Numai cheia de mediu înseamnă indisponibilitate și omiterea discovery.
• Definițiile personalizate dinaintea upgrade-ului sunt puse în carantină, deoarece proveniența administratorului nu fusese înregistrată. Reimportați-le ca administrator și reactivați-le per utilizator. Editarea directă le pune iar în carantină; folosiți fluxul install/update pentru source path/hash.
• Credentials sunt legate de rută, contractul auth, definiție și source. După o schimbare, salvați-le din nou. Valorile vechi, fără binding, migrează numai pe ruta inclusă ancorată exact.
• Un plugin importat poate folosi api_url ca alias legacy; endpoint are prioritate. Pentru altă listă de modele, folosiți models_endpoint complet, validat fără redirect-uri.
• Activați după salvarea endpoint-ului/credential-ului. Activarea derivă /models și folosește credential-ul utilizatorului care activează, dacă nu există models_endpoint. Salvarea/resetarea câmpurilor face refresh și așteaptă înainte de reîncărcarea UI. Activarea este per cont.
• În Settings → Plugins, selectați Refresh models. Tabelul este numai pentru citire pentru contul curent. Un eșec temporar păstrează catalogul anterior sau fallback-ul model_map, deci o verificare încheiată nu dovedește sănătatea endpoint-ului.
• Discovery automat necesită un răspuns OpenAI compatibil data. Cataloagele sunt stocate per utilizator fără modificarea JSON-ului. Activarea normală păstrează catalogul anterior dacă furnizorul este indisponibil, iar schimbarea conexiunii îl golește mai întâi și folosește model_map la eșec.
• Modelele de imagine, override-urile și cheile sunt rezolvate pentru utilizatorul curent; verificați autentificarea dacă apare alt cont.
• Dacă un non-admin actualizat avea o valoare de rutare, Reset o elimină, astfel încât schimbarea ulterioară a rolului să nu o reactiveze, și curăță modelele vechi descoperite.
• Cererile pornesc din backend; localhost într-un container înseamnă containerul.
• Cererile furnizorilor nu urmează redirect-uri. Configurați URL-ul final validat.

Chat-ul folosește furnizorul greșit sau indisponibil

Același ID de model poate exista în Ollama și în mai multe pluginuri. Sesiunile Chat și preferințele implicite stochează furnizorul și ID-ul brut, astfel încât numele identice rămân independente.

• Dacă este indisponibil, reactivați/reinstalați pluginul exact și verificați harta modelelor.
• Dacă a fost eliminat intenționat, selectați un înlocuitor. Nu este redirecționat către același nume al altui furnizor.
• Sesiunile vechi fără metadata de furnizor păstrează rutarea legacy numai după nume și afișează „provider not recorded”. Selectați din nou Ollama/pluginul pentru a-l fixa.
• Un personaj rămâne persona:<id>. Selecțiile noi scriu modelul Ollama suport, iar cele istorice fără metadata rămân compatibile.

Probleme cu Work

Work lipsește sau raportează Runtime unavailable

Necesită un cont autentificat curent cu acces Work — administrator sau utilizator activ după ce administratorul îl deschide din fila User Management din Settings. Runtime-ul containerului trebuie să fie accesibil backend-ului:

docker info
docker version

În backend-ul Docker implicit, confirmați că Docker rulează și că utilizatorul sistemului de operare poate executa WORK_DOCKER_COMMAND. npx nu instalează Docker. Fără runtime, restul aplicației rămâne disponibil și comenzile modelului nu rulează pe host.

Fișierele Compose montează socket-ul host-ului. În Kubernetes, activați Pod/PVC cu work.enabled=true, niciodată socket-ul runtime al node-ului. Dacă apare în continuare Runtime unavailable, pagina indică motivul:

Mesaj	Cauză și soluție
The "docker" CLI is not installed…	Imagine personalizată fără docker-cli. Folosiți imaginea oficială sau setați WORK_DOCKER_COMMAND.
No Docker daemon is reachable…	Mount-ul socket a fost eliminat sau daemon-ul este oprit. Restabiliți-l și porniți Docker.
The Docker socket is mounted but…cannot open	Grup socket diferit. Setați DOCKER_GID în .env și recreați containerul.
Ecranul sau sunetul Work se închide cu WebSocket 1006 și log screen is unreachable	Backend-ul din container apelează propriul loopback. Pe Docker Desktop folosiți WORK_DOCKER_PUBLISHED_HOST=host.docker.internal livrat implicit; pe Docker Engine nativ setați în plus WORK_PREVIEW_BIND la gateway-ul nepublic al punții Docker și recreați Libre WebUI.

Citiți grupul printr-un container, deoarece un host macOS raportează altă valoare:

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

Acest socket oferă control echivalent cu root asupra host-ului Docker. Citiți Work: spații izolate pentru consecințele deployment-ului.

Modelul nu acceptă instrumente

Work are nevoie de un model chat cu instrumente. În Ollama, selectați un model instalat care declară tools. Pentru un plugin:

• Confirmați că pluginul este activ, modelul apare în listă, administratorul are cheie API și modelul exact acceptă apeluri de instrumente.

Libre nu redirecționează implicit un Work eșuat către alt furnizor.

Cererea Work returnează HTTP 429

A fost atinsă limita de sarcini sau runtime-uri active. Implicit sunt permise două sarcini cu container în instanță și una per utilizator; un preview ocupă și el capacitate. Așteptați, opriți preview-ul sau verificați WORK_MAX_ACTIVE_RUNTIMES_* și WORK_MAX_TASKS_*.

Instalarea pachetelor sau accesul la rețea eșuează

Sarcinile noi folosesc bridge-ul Docker pentru pachete și preview. Verificați DNS, proxy, registry și Activity. Cheile SSH ale host-ului, credentials cloud, profilurile browserului și socket-ul nu sunt montate.

Preview-ul Work nu pornește

• Serverul trebuie să se lege la 0.0.0.0 pe WORK_PREVIEW_PORT (implicit 4173).
• O comandă goală detectează scriptul dev din package.json sau index.html, inclusiv o singură aplicație imbricată.
• Dacă sunt detectate mai multe aplicații sau niciun entry point, introduceți o comandă explicită. Aceasta pornește în /workspace; folosiți cd <app-directory> && ... pentru o aplicație imbricată.
• Extindeți detaliile erorii și opriți un preview existent înainte de altă comandă.

URL-ul preview-ului folosește un port loopback dinamic, deci browserul și backend-ul trebuie să fie pe același sistem. Un browser la distanță nu poate accesa loopback, iar HTTPS poate bloca HTTP drept mixed content.

Un fișier din workspace nu se deschide sau nu se salvează

API-ul de fișiere acceptă UTF-8 până la 2 MB. Dacă fișierul s-a schimbat după deschidere, reîncărcați-l înainte de salvare. Formatarea acceptă numai tipurile documentate sub 100.000 de caractere/4.000 de linii, iar highlighting-ul este dezactivat pentru fișiere mari.

Editările nesalvate sunt un draft al browserului, nu un înlocuitor pentru salvarea persistentă.

Sarcina sau preview-ul s-a oprit

Oprirea unei execuții/preview sau repornirea backend-ului oprește procesele temporare, dar păstrează volumul nominalizat. Redeschideți sarcina/preview-ul. Ștergerea după confirmare elimină definitiv sarcina și workspace-ul.

Probleme de autentificare și înscriere

Primul utilizator nu este administrator

Numai primul cont dintr-o bază nouă devine administrator. Bazele existente păstrează utilizatorii și rolurile.

Erori JWT

Setați un secret stabil în producție:

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

Schimbarea JWT_SECRET invalidează sesiunile existente.

Turnstile blochează înscrierea

Este activat numai când sunt setate ambele chei:

TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...

Confirmați cheia site-ului, domeniul și un secret valid.

Redirect-urile OAuth eșuează

Setați URL-urile callback în dashboard-ul furnizorului și în .env al backend-ului:

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

Probleme cu Chat pentru documente

Sunt acceptate PDF, Office, Markdown, HTML, cod și CSV până la 10 MB.

Dacă funcționează căutarea, dar nu regăsirea semantică:

1. Instalați un model de embeddings precum nomic-embed-text.
2. Activați embeddings.
3. Regenerați din setările documentelor sau prin API.

ollama pull nomic-embed-text

Căutarea după cuvinte-cheie funcționează și fără embeddings.

Probleme cu preview-ul artefactelor

Pentru jocuri sau HTML interactiv, solicitați un fișier HTML autonom, cu CSS și JavaScript inline.

Dacă are nevoie de tastatură:

• Faceți clic în preview sau deschideți-l în propria filă. Nu vă bazați pe fișiere locale din afara răspunsului.

Libre combină index.html, CSS și JavaScript, dar un document autonom este mai fiabil.

Probleme Docker

Containerul nu poate accesa Ollama

Folosiți fișierul Compose pentru Ollama extern când acesta nu se află în aceeași stivă:

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

Datele nu persistă

Montați un volum persistent și setați DATA_DIR. Cheia de criptare este stocată persistent împreună cu DATA_DIR/Docker.

Resetarea datelor locale

Opriți backend-ul, copiați și eliminați directorul de date. Valoarea implicită în dezvoltare este backend/data.

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

Reporniți backend-ul și creați un cont nou.

Problema persistă

Deschideți un issue și includeți:

• versiunea/commit-ul Libre WebUI, metoda de instalare, sistemul de operare și versiunile Node.js/Ollama/Docker;
• docker info pentru Work, logurile backend, erorile consolei, modelul/furnizorul exact și ieșirea Work Activity.