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.
• Le credenziali salvate sono legate a route, contratto di autenticazione, definizione e origine in vigore al momento dell’inserimento. Aggiungere o rimuovere modelli le conserva. Dopo aver cambiato un endpoint o qualsiasi altra parte della definizione, salva di nuovo la credenziale di quell’account. Una vecchia credenziale non vincolata migra automaticamente solo su una route inclusa ancorata 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 in Impostazioni → Gestione utenti → Accesso e criteri → Accesso a Work. 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.

Problemi del motore Strands

Il motore Strands integrato riporta il proprio stato a qualsiasi account che può usarlo:

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

Una risposta 403 indica che il motore non è abilitato per quell'account.

La pagina Strands non compare

La barra laterale nasconde Strands quando l'account non ha accesso. Controlla Impostazioni → Gestione utenti → Accesso e criteri → Motore Strands. Disattivo blocca tutti, amministratori compresi, e Amministratori la nasconde agli utenti normali. Se il controllo è bloccato, LIBRE_STRANDS_ACCESS fissa la modalità: impostala su admins o all-users, oppure rimuovila per gestire la modalità dall'interfaccia. Qualsiasi valore diverso da disabled, admins o all-users blocca il motore su disattivato.

Nessun modello nell'elenco

Strands pilota solo i modelli che Libre WebUI già serve. Abilita Ollama e scarica un modello di chat, oppure attiva un plugin provider di chat in Impostazioni → Plugin. L'elenco dei modelli di Strands includerà quindi quei modelli.

Un passaggio di Work su Strands fallisce perché gli strumenti non sono supportati

Con Motore: Strands, l'agente Strands pianifica ogni passaggio tramite chiamate agli strumenti, quindi il modello del provider deve supportare le chiamate agli strumenti. Se non lo fa, Work segnala che il modello non dichiara il supporto agli strumenti (WORK_MODEL_TOOLS_UNSUPPORTED). Scegli un modello che supporti gli strumenti nel controllo Modello di Work ed esegui di nuovo l'attività.

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