Risoluzione dei problemi

Parti dal livello che non funziona: browser, frontend, backend, Ollama, plugin o rete.

Controlli rapidi

# 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

In sviluppo frontend è di solito http://localhost:5173, backend http://localhost:3001; npx libre-webui serve su http://localhost:8080.

Libre WebUI non si avvia

Controlla Node e dipendenze

node --version
npm install
npm run dev

Serve Node.js 22.22 o più recente.

Porta occupata

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

Ferma il processo o cambia porta.

Il backend non scrive dati

Usa DATA_DIR o backend/data. Le esecuzioni source risolvono valori relativi dal backend: DATA_DIR=./data seleziona backend/data, DATA_DIR=./backend/data seleziona backend/backend/data. Verifica permessi. Senza valore conserva il percorso storico se è l'unico store. Se entrambi hanno dati, ferma, fai backup e scegli/migra; Libre non unisce né copia database divergenti.

Gli endpoint distinguono processo vivo e app pronta:

• /health e /health/live restituiscono 200 se serve HTTP; provider opzionali non incidono.
• /health/ready restituisce 503 se database, schema, storage o dipendenza necessaria non è disponibile; non aspetta provider opzionali e omette dettagli pubblici.
• /health/deep esegue integrità SQLite/foreign key e sonde opzionali come Ollama. Un problema opzionale è warning. Richiede Bearer admin e non è adatto a probe frequenti.

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

Il browser non raggiunge il backend

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

VITE_API_BASE_URL viene usato dal frontend quando è impostato.

VITE_WS_BASE_URL è opzionale ma condivisa da Chat e terminale Work. Usa URL assoluto ws:/wss:; supporta prefisso wss://example.com/libre. Niente credenziali, query o fragment. Riavvia/ricompila dopo variabili Vite.

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

Per telefono/LAN/Tailscale non usare localhost sul telefono; usa l'IP e:

npm run dev:host

Questo serve il frontend sulla porta 8080 e instrada in proxy il traffico API e WebSocket verso il backend locale sulla porta 3001. Solo la porta 8080 deve essere raggiungibile dall'altro dispositivo. Se VITE_API_BASE_URL o VITE_WS_BASE_URL è impostata in frontend/.env, assicurati che quegli URL siano raggiungibili dall'altro dispositivo, oppure rimuovile per usare il proxy del dev server.

Chat non trasmette dietro proxy inverso

Sintomo: messaggio inviato, nessuna risposta, errore WebSocket. Verifica upgrade e connessioni lunghe.

Con CORS_ORIGIN o BASE_URL, Origin del browser deve coincidere. Impostane uno in remoto; senza, è permissivo per sviluppo. Electron/non-browser può ometterlo, ma scambia Authorization per ticket monouso. Proteggi con TLS e controlli della API.

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

Gli esempi assumono proxy sull'host Docker e porta 8080; nella rete Compose usa 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;
}

Valida con nginx -t e ricarica.

Caddy

reverse_proxy supporta WebSocket automaticamente:

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'

Se cade dopo, controlla timeout di proxy/load balancer; in Traefik transport.respondingTimeouts.

Ollama non rilevato

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

OLLAMA_BASE_URL=http://localhost:11434

Con Libre in Docker e Ollama sull'host, usa Compose esterno o imposta OLLAMA_BASE_URL a un indirizzo raggiungibile.

Problemi download modelli

ollama pull gemma4:12b

Se fallisce nel terminale, il problema è esterno.

Per Ollama Cloud usa il filtro cloud; Libre normalizza i suffix, quindi non aggiungere :cloud. Gli admin possono disabilitare download agli utenti normali.

Chat lenta o non riuscita

• Modello più piccolo.
• Controlla ollama ps.
• Riduci contesto/token.
• Verifica RAM/VRAM.
• Verifica chiave e quota provider.

Generazione immagini OpenAI non disponibile

• Attiva OpenAI, salva chiave utente o OPENAI_API_KEY.
• Abilita immagini e scegli GPT Image.
• Preferisci gpt-image-2; gli ID vecchi sono deprecati.
• Lascia image_endpoint vuoto salvo endpoint compatibile; /responses//chat/completions non gestiscono Image API.
• Verifica eleggibilità organizzazione.

La disponibilità usa credenziale utente corrente o fallback trusted; chiave di altro utente non espone modelli.

Problemi endpoint provider

Se un provider OpenAI-compatible riceve richieste sul percorso errato, controlla Impostazioni → Plugin:

• Chat Completions per /chat/completions, Responses per /responses.
• Inserisci la radice, come https://provider.example/v1, in Base URL.
• Lascia API Path vuoto o inserisci un percorso con slash.
• Un endpoint legacy realmente custom ha priorità; cancellalo tornando a Base URL/API Path. Valori uguali al vecchio default vengono ignorati dopo upgrade. Suffix noti determinano il formato.

JSON importato supporta formati OpenAI Chat Completions, Responses, Anthropic o Gemini. Formati proprietari richiedono adattatore; cambiare URL non traduce.

HTTP non cifra credenziali/traffico; usalo solo in rete fidata. Base URL non può contenere query/fragment; percorsi relativi non possono contenere traversal letterale o ricodificato, query o fragment. Codifica eccessiva viene rifiutata.

Refresh sostituisce suffix noti con /models. Attivazione, refresh e override usano endpoint/chiave dell'utente. Salvare/rimuovere chiave e reset connessione aggiorna; generazione no. ID per utente non sovrascrivono JSON. Senza route compatibile, configura model_map.

Provider request non seguono redirect, inclusi discovery, Chat, Work, immagini, embedding e TTS. Configura destinazione finale.

Se Work segnala routing cambiato, avvia nuova esecuzione dopo l'aggiornamento: si ferma prima della richiesta successiva per non riprodurre stato in altro confine.

Le richieste originano dal backend. Nel container localhost è Libre WebUI, non host. Usa DNS come http://ai-gateway:8080/v1; http://host.docker.internal:8080/v1 solo se disponibile. HTTP resta plaintext.

Immagini, override e chiavi sono risolti per utente corrente.

Regole:

• Solo admin modifica routing; utenti comuni salvano generazione, credenziali e attivazione.
• endpoint/api_url devono essere URL completi, come https://provider.example/v1/chat/completions. La radice base_url va con api_mode/api_path.
• Solo HTTP(S) assoluti; HTTP solo fidato.
• Vuoto usa definizione; malformato viene rifiutato.
• Chiave ambientale solo con definizione inclusa non shadowed e routing/autenticazione/capacità/default trusted. Importate, scrivibili con ID incluso e route custom richiedono credenziale account. Altrimenti provider indisponibile.
• Definizioni custom pre-upgrade sono quarantinate; reimporta come admin e riattiva. Modifica diretta le riquarantina.
• Credenziali sono legate a route, contratto, definizione e origine; risalvale dopo cambio. Legacy migra solo sulla rotta esatta.
• api_url alias; endpoint prevale. models_endpoint per lista completa, validato senza redirect.
• Attiva dopo endpoint/credenziale. Deriva /models e usa credenziale attivante. Salvare/reset campi aggiorna e attende. Attivazione per account.
• Aggiorna modelli controlla catalogo read-only. Errore transitorio mantiene il precedente o model_map; non prova salute.
• Discovery richiede array data. Risultati per utente. Cambiare connessione cancella prima e usa fallback.
• Immagini usano utente corrente.
• Per un vecchio routing non-admin usa Reset per eliminarlo insieme al catalogo.
• localhost nel container è il container.
• Nessun redirect.

Chat usa provider errato o indisponibile

Lo stesso ID può esistere in Ollama e più plugin. Sessioni/preferenze correnti salvano provider e ID.

• Se indisponibile, riattiva/reinstalla quello esatto e controlla la mappa.
• Se rimosso, scegli sostituto; niente redirect a omonimo.
• Record legacy senza metadata mantengono routing per nome e mostrano "provider non registrato". Riseleziona per fissare.
• Personas mantengono persona:<id>; nuove registrano Ollama, vecchie restano compatibili.

Problemi Work

Work assente o runtime non disponibile

Serve account autenticato con accesso: admin o utente attivo dopo l'apertura nella scheda Gestione utenti in Impostazioni. Il runtime deve essere disponibile:

docker info
docker version

Nel Docker default, verifica daemon e permesso di eseguire WORK_DOCKER_COMMAND. npx non installa Docker. Senza runtime il resto funziona e i comandi non vengono mai eseguiti direttamente sull'host.

Compose monta il socket. Su Kubernetes abilita work.enabled=true e non montare socket nodo. Messaggi:

Messaggio	Causa e soluzione
The "docker" CLI is not installed…	Immagine custom senza docker-cli; usa ufficiale o WORK_DOCKER_COMMAND.
No Docker daemon is reachable…	Mount rimosso o daemon fermo.
The Docker socket is mounted but…cannot open	Gruppo diverso; imposta DOCKER_GID in .env e ricrea.
Schermo o audio di Work si chiudono con WebSocket 1006 e log screen is unreachable	Il backend nel container contatta il proprio loopback. Su Docker Desktop usa il valore incluso WORK_DOCKER_PUBLISHED_HOST=host.docker.internal; su Docker Engine nativo imposta anche WORK_PREVIEW_BIND sul gateway non pubblico del bridge Docker, poi ricrea Libre WebUI.

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

Il socket equivale a root. Vedi Work: spazi isolati.

Modello senza strumenti

Scegli Ollama che espone tools. Per plugin verifica attivo, modello nella lista, chiave admin e supporto tool del modello. Nessun fallback.

HTTP 429

Raggiunto limite attività/runtime. Default: due attività container nella istanza e una per utente; preview occupa capacità. Attendi, ferma preview o rivedi WORK_MAX_ACTIVE_RUNTIMES_*/WORK_MAX_TASKS_*.

Installazione pacchetti o rete non riuscita

Le nuove attività usano bridge per download. Controlla DNS Docker, proxy, registry e output in Attività. Non monta SSH, credenziali cloud, profili browser o socket.

Preview non parte

• Server su 0.0.0.0 e WORK_PREVIEW_PORT (default 4173).
• Comando vuoto rileva package.json dev o index.html, anche app annidata singola.
• Con più app/nessun entry point inserisci comando esplicito; parte da /workspace, usa cd <app-directory> && ....
• Espandi dettagli.
• Ferma preview precedente.

Gli URL usano porta loopback dinamica. Browser e backend devono stare sulla stessa macchina; browser remoto non raggiunge loopback e HTTPS può bloccare HTTP mixed content.

File non apre o salva

API accetta testo UTF-8 fino a 2 MB. Se cambiato dopo apertura, ricarica. Formattazione sotto 100.000 caratteri/4.000 righe; highlighting si ferma su grandi file. La bozza browser non sostituisce il salvataggio.

Attività o preview fermata

Stop/restart elimina processi temporanei ma mantiene volume. Riapri e riavvia. Eliminare rimuove attività e spazio definitivamente.

Problemi login e registrazione

Primo utente non admin

Solo il primo account in database nuovo è admin; database esistenti mantengono ruoli.

Errori JWT

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

Cambiare JWT_SECRET invalida sessioni.

Turnstile blocca

TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...

Richiede entrambe; controlla dominio e secret.

Redirect OAuth fallisce

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

Problemi Chat documenti

Accetta PDF, Office, Markdown, HTML, codice e CSV fino a 10 MB. Se semantica non funziona:

1. Installa nomic-embed-text.
2. Abilita embedding.
3. Rigenera.

ollama pull nomic-embed-text

La ricerca keyword funziona comunque.

Problemi preview artefatti

Per giochi/HTML chiedi un file completo con CSS/JavaScript inline. Per tastiera, clicca dentro, apri in scheda propria e non dipendere da file locali. Libre può unire index.html + CSS + JavaScript, ma standalone è più affidabile.

Problemi Docker

Container non raggiunge Ollama

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

Dati non persistono

Monta volume persistente e imposta DATA_DIR; la chiave resta nello storage persistente.

Reimpostare dati locali

Ferma, fai backup e rimuovi la directory, default backend/data.

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

Riavvia e crea account.

Ancora bloccato

Apri issue con:

• versione e commit
• metodo installazione
• sistema operativo
• versione Node.js
• versione Ollama
• Docker e docker info per Work
• log backend
• errori console
• modello/provider esatto
• output Attività quando fallisce