Dépannage

Commencez par la couche qui échoue : navigateur, interface, serveur dorsal, Ollama, plugin fournisseur ou réseau du déploiement.

Vérifications rapides

# 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

En développement, l’interface s’exécute généralement sur http://localhost:5173 et le serveur dorsal sur http://localhost:3001. Le parcours empaqueté npx libre-webui sert l’application sur http://localhost:8080.

Libre WebUI ne démarre pas

Vérifier Node et les dépendances

node --version
npm install
npm run dev

Node.js 22.22 ou version ultérieure est requis.

Port déjà utilisé

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

Arrêtez l’ancien processus ou configurez un autre port.

Le serveur dorsal ne peut pas écrire les données

Le serveur dorsal stocke les données sous DATA_DIR si cette valeur est définie, sinon sous backend/data. Les lancements depuis les sources résolvent une valeur DATA_DIR relative depuis le répertoire du serveur dorsal, et non depuis le répertoire actuel de l’environnement. Ainsi, DATA_DIR=./data sélectionne backend/data, tandis que l’ancienne valeur prise en charge DATA_DIR=./backend/data sélectionne backend/backend/data. Vérifiez que le répertoire choisi est accessible en écriture. Sans DATA_DIR, Libre conserve l’ancien répertoire s’il s’agit du seul stockage existant. Si les deux emplacements contiennent des données, arrêtez Libre, sauvegardez-les tous les deux, puis choisissez ou migrez volontairement ; Libre ne fusionne ni ne copie jamais des bases divergentes.

Les points d’intégrité distinguent volontairement un processus en cours d’exécution d’une application utilisable :

• /health et /health/live renvoient 200 tant que le serveur dorsal peut servir HTTP. Les fournisseurs de modèles facultatifs n’influencent pas l’état actif.
• /health/ready renvoie 503 lorsqu’une base de données, un schéma, un stockage ou une dépendance de plateforme enregistrée et requise est indisponible. Il n’attend pas les fournisseurs de modèles facultatifs. Sa réponse publique omet les messages d’erreur et les détails internes.
• /health/deep exécute dans un processus borné les contrôles d’intégrité et de clés étrangères SQLite, puis regroupe les sondes facultatives des fournisseurs au niveau du serveur, comme Ollama. La panne d’un fournisseur facultatif apparaît comme avertissement et ne rend pas les dépendances requises indisponibles. Ce point exige un jeton Bearer d’un administrateur actuel et ne convient pas à une sonde fréquente d’orchestrateur.

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

Le navigateur ne peut pas joindre le serveur dorsal

En développement local, l’interface utilise VITE_API_BASE_URL si elle est définie, sinon revient au serveur dorsal de développement.

Exemple de fichier .env de l’interface :

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

VITE_WS_BASE_URL est facultative. Lorsqu’elle est définie, elle sert de base commune aux sockets de Chat et du terminal Work. Utilisez une URL ws: ou wss: absolue ; un préfixe comme wss://example.com/libre est pris en charge. N’ajoutez ni identifiants, ni paramètres de requête, ni fragment. Redémarrez ou recompilez l’interface après avoir modifié une variable Vite.

Exemple de fichier .env du serveur dorsal :

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

Depuis un téléphone, un réseau local ou Tailscale, ne dirigez pas le navigateur vers localhost ; utilisez l’adresse IP locale ou Tailscale de l’ordinateur portable et exécutez le serveur de développement avec une liaison à l’hôte :

npm run dev:host

Cela sert l’interface sur le port 8080 et redirige le trafic API et WebSocket vers le serveur dorsal local sur le port 3001. Seul le port 8080 doit être accessible depuis l’autre appareil. Si VITE_API_BASE_URL ou VITE_WS_BASE_URL est défini dans frontend/.env, assurez-vous que ces URL sont accessibles depuis l’autre appareil, ou supprimez-les pour utiliser le proxy du serveur de développement.

Chat ne diffuse pas derrière un proxy inverse

Le symptôme typique est l’envoi des messages sans affichage de réponse, accompagné d’une erreur de connexion WebSocket dans la console du navigateur. Vérifiez que le proxy autorise les mises à niveau WebSocket et ne ferme pas les connexions de longue durée.

Si l’une de ces valeurs est configurée, les mises à niveau du navigateur qui envoient un en-tête Origin sont comparées à CORS_ORIGIN et BASE_URL. Définissez-en au moins une pour un déploiement distant ; sans aucune, le filtre Origin reste permissif pour le développement local. Electron et les autres clients qui ne sont pas des navigateurs peuvent omettre Origin, mais doivent tout de même échanger d’abord leur en-tête Authorization contre un ticket à usage unique de courte durée. Maintenez le serveur dorsal derrière TLS et les mêmes contrôles d’accès réseau ou de proxy inverse que l’API HTTP.

Pour un nom d’hôte public, autorisez cette origine de navigateur dans le service Libre WebUI :

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

Les exemples nginx et Caddy ci-dessous supposent que le proxy s’exécute sur l’hôte Docker, où la configuration Compose du dépôt publie Libre WebUI sur le port 8080. Si le proxy rejoint le réseau Compose, utilisez libre-webui:3001 comme adresse amont.

nginx

nginx exige la transmission explicite des en-têtes de mise à niveau. Le délai de lecture prolongé maintient ouverte une connexion de discussion inactive pendant le travail du modèle.

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

Rechargez nginx après avoir validé la configuration avec nginx -t.

Caddy

La directive reverse_proxy de Caddy prend en charge les WebSockets sans configuration supplémentaire ; aucun en-tête de mise à niveau n’est nécessaire :

chat.example.com {
    reverse_proxy 127.0.0.1:8080
}

Traefik

Traefik gère lui aussi les mises à niveau WebSocket par défaut. Lorsque son fournisseur Docker partage le réseau de Libre WebUI, seuls les libellés habituels du routeur et du service sont nécessaires, par exemple :

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'

Si les flux se connectent puis s’interrompent, vérifiez le délai d’inactivité de tout proxy ou répartiteur de charge placé devant Traefik. Si Traefik applique lui-même la limite, ajustez le paramètre transport.respondingTimeouts du point d’entrée.

Ollama n’est pas détecté

Vérifier qu’Ollama fonctionne

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

Configurer une URL Ollama personnalisée

Fichier .env du serveur dorsal :

OLLAMA_BASE_URL=http://localhost:11434

Si Libre WebUI s’exécute dans Docker et Ollama sur l’hôte, utilisez le fichier Compose pour Ollama externe ou définissez OLLAMA_BASE_URL sur l’adresse hôte accessible depuis le conteneur.

Problèmes de récupération des modèles

Commencer par récupérer le modèle dans le terminal

ollama pull gemma4:12b

Si cette commande échoue, le problème ne vient pas de Libre WebUI.

Modèles cloud

Utilisez le filtre cloud du gestionnaire de modèles pour les modèles Ollama Cloud. Libre WebUI normalise les suffixes cloud requis dans ce parcours ; les utilisateurs ne devraient pas avoir à ajouter manuellement :cloud aux entrées prises en charge.

Un utilisateur ne peut pas récupérer de modèles

Les administrateurs peuvent interdire aux utilisateurs ordinaires de récupérer des modèles. Vérifiez les paramètres d’administration si une personne non administratrice peut parcourir les modèles sans pouvoir les installer.

Chat est lent ou échoue

• Utilisez un modèle plus petit.
• Vérifiez les modèles chargés avec ollama ps.
• Réduisez la longueur du contexte.
• Réduisez le nombre maximal de jetons des réponses très longues.
• Vérifiez que le modèle tient dans la RAM/VRAM.
• Pour les plugins fournisseurs, vérifiez la clé d’API et le quota du fournisseur.

La génération d’images OpenAI est indisponible

• Activez le fournisseur OpenAI intégré. Enregistrez une clé d’API pour l’utilisateur actuel ou configurez la solution de repli OPENAI_API_KEY du fournisseur intégré fiable.
• Ouvrez les paramètres de génération d’images, activez-la et sélectionnez l’un des modèles GPT Image annoncés.
• Préférez gpt-image-2. Les anciens identifiants GPT Image ne restent disponibles que pour la compatibilité avec les configurations existantes et sont obsolètes en amont.
• Laissez le remplacement OpenAI image_endpoint vide, sauf si vous exploitez un point de terminaison compatible. Un point Chat /responses ou /chat/completions ne peut pas traiter les requêtes de l’API Image.
• Si OpenAI refuse une requête GPT Image malgré une clé et un quota valides, vérifiez que l’organisation de l’API est autorisée à utiliser ces modèles.

La disponibilité des images est évaluée avec l’identifiant enregistré de l’utilisateur actuel ou la valeur d’environnement du fournisseur intégré fiable. Une clé enregistrée uniquement dans les paramètres d’une autre personne n’expose aucun modèle d’images.

Problèmes de points de terminaison des fournisseurs

Si un fournisseur compatible avec OpenAI reçoit des requêtes au mauvais chemin, vérifiez ses paramètres sous Paramètres → Plugins :

• Choisissez Chat Completions pour les charges utiles /chat/completions ou Responses pour les charges utiles /responses.
• Saisissez la racine de l’API, par exemple https://provider.example/v1, comme URL de base.
• Laissez le chemin de l’API vide pour utiliser celui du mode, ou saisissez un chemin commençant par une barre oblique fourni par le fournisseur.
• Un ancien point de terminaison complet réellement personnalisé reste volontairement prioritaire ; effacez-le pour revenir à l’URL de base et au chemin de l’API. Les valeurs stockées qui correspondent simplement à l’ancienne valeur du manifeste intégré sont automatiquement ignorées après une mise à niveau. Si un point personnalisé se termine par /chat/completions ou /responses, ce suffixe détermine aussi le format des requêtes afin d’empêcher l’envoi d’une mauvaise charge utile.

Le JSON d’un plugin importé prend en charge les fournisseurs qui utilisent un format filaire compatible avec OpenAI Chat Completions, OpenAI Responses, Anthropic ou Gemini. Si le fournisseur utilise une charge utile, un événement de diffusion, un appel d’outil ou une réponse propriétaire, il exige un adaptateur du serveur dorsal ; modifier seulement le point de terminaison ne peut pas le traduire.

Les URL peuvent employer HTTP ou HTTPS. HTTP transmet les identifiants et le trafic sans chiffrement de transport ; réservez-le à une passerelle auto-hébergée sur un réseau fiable et préférez HTTPS dès que TLS est disponible. Les URL de base ne peuvent comporter ni requête ni fragment, et les chemins relatifs ne peuvent contenir de segments de traversée littéraux ou encodés plusieurs fois, ni requêtes ni fragments. Un encodage excessif qui ne se stabilise pas dans la limite de validation est refusé.

L’actualisation des modèles remplace les suffixes d’opérations connus, dont /responses, par /models. L’activation, l’actualisation explicite et les remplacements enregistrés utilisent le point de terminaison et la clé d’API de l’utilisateur actuel. Enregistrer ou retirer sa clé et réinitialiser les remplacements actualise aussi la liste ; les paramètres de génération sans rapport ne le font pas. Les identifiants découverts sont stockés par utilisateur et ne remplacent jamais le JSON partagé. Si le fournisseur ne prend pas en charge la route dérivée, configurez les identifiants manuellement dans son model_map.

Les requêtes aux fournisseurs ne suivent volontairement aucune redirection HTTP, y compris pour la découverte, Chat, Work, les images, les plongements et la synthèse vocale. Configurez l’URL de destination finale. Ce comportement sécurisé empêche un en-tête d’autorisation de parvenir à une destination non validée.

Si Work signale que le routage a changé pendant une exécution, lancez-en une nouvelle après avoir terminé la modification. Work s’arrête volontairement avant la requête suivante pour que l’ancien état d’outil ne soit pas rejoué vers un autre mode, point de terminaison ou périmètre d’authentification par clé d’API.

Les requêtes proviennent du serveur dorsal : localhost désigne donc le conteneur Libre WebUI lorsque celui-ci est conteneurisé, et non automatiquement l’hôte. Avec Compose ou Kubernetes, utilisez le nom DNS du service de la passerelle, par exemple http://ai-gateway:8080/v1. N’utilisez http://host.docker.internal:8080/v1 que si l’environnement de conteneurs expose cet alias. Le trafic HTTP reste en clair même si le nom se résout en privé.

Les modèles d’images, remplacements et clés sont eux aussi résolus pour l’utilisateur actuel. Si une requête semble utiliser les paramètres d’un autre compte, vérifiez qu’elle est authentifiée comme la personne attendue.

Les règles de sécurité et de propriété suivantes s’appliquent également :

• Connectez-vous comme administrateur pour modifier le routage. Les définitions et champs de connexion sont gérés par l’instance ; les utilisateurs ordinaires peuvent toujours enregistrer leurs réglages de génération, identifiants et état d’activation.
• Avec l’ancien remplacement endpoint ou api_url, saisissez l’URL complète de l’opération, chemin compris (par exemple https://provider.example/v1/chat/completions). Saisissez une racine d’API uniquement dans base_url, avec api_mode et éventuellement api_path.
• Les URL absolues HTTP et HTTPS sont acceptées. N’utilisez HTTP que pour une passerelle auto-hébergée sur un réseau fiable, car les clés d’API, prompts et réponses sont sinon transmis sans chiffrement.
• Un remplacement vide utilise le point de terminaison intégré à la définition. Une valeur explicite mal formée ou non sûre est refusée ; Libre WebUI n’envoie pas silencieusement la requête au fournisseur intégré.
• Une clé d’environnement du déploiement n’est utilisée que si une définition intégrée non masquée conserve sa racine fiable, ses champs d’authentification, les points de terminaison et sélecteurs des capacités et les valeurs par défaut des variables de routage. Les définitions importées ou accessibles en écriture qui réutilisent un identifiant intégré, ainsi que les routes personnalisées enregistrées, exigent un identifiant du même compte. Si seule la clé d’environnement existe, Libre WebUI signale volontairement le fournisseur comme indisponible et ignore la découverte.
• Les définitions personnalisées antérieures à une mise à niveau sont mises en quarantaine, car les anciennes versions n’enregistraient pas la provenance de l’administrateur. Réimportez le JSON comme administrateur, puis faites-le réactiver par chaque utilisateur. Modifier directement un JSON approuvé le remet en quarantaine ; utilisez le parcours d’installation ou de mise à jour afin d’enregistrer son chemin et son hachage.
• Les identifiants enregistrés sont liés à la route, au contrat d’authentification, à la définition et à la source en vigueur lors de leur saisie. Après une modification, réenregistrez l’identifiant du compte. Un ancien identifiant non lié ne migre automatiquement que sur une route intégrée ancrée exacte.
• Les plugins importés peuvent employer api_url comme alias d’une URL complète. endpoint l’emporte si les deux sont définis. Si la découverte se trouve ailleurs, définissez son URL complète dans models_endpoint ; elle est validée et aucune redirection n’est suivie.
• Activez le plugin après avoir enregistré le point de terminaison et l’identifiant. L’activation dérive une URL /models et utilise l’identifiant de la personne, sauf si models_endpoint est défini. Enregistrer ou réinitialiser ces champs actualise aussi la découverte, qui termine avant le rechargement de l’interface. L’activation est propre au compte ; chaque autre utilisateur doit activer séparément le plugin partagé.
• Dans Paramètres → Plugins, sélectionnez le fournisseur puis Actualiser les modèles pour vérifier explicitement son catalogue. Le tableau en lecture seule affiche les identifiants configurés ou découverts du compte actuel. Un échec passager conserve le catalogue précédent ou le model_map de repli s’il n’existe aucun résultat ; un contrôle terminé ne prouve donc pas que le point distant est sain.
• La découverte automatique exige un tableau data compatible avec OpenAI. Les catalogues réussis sont stockés par utilisateur sans modifier le JSON partagé. Une activation normale conserve le catalogue antérieur si la découverte est indisponible. Modifier ou réinitialiser un champ de connexion efface d’abord ce catalogue ; une actualisation échouée utilise donc le model_map existant. Configurez-y les identifiants de repli si nécessaire.
• La disponibilité des images, les remplacements et les clés sont aussi résolus pour l’utilisateur actuel. Vérifiez l’identité de la requête si elle semble employer les paramètres d’un autre compte.
• Si un compte non administrateur mis à niveau avait enregistré une valeur de routage, utilisez Réinitialiser pour ce plugin. La valeur ignorée est supprimée afin qu’un changement de rôle ultérieur ne l’active pas. La réinitialisation efface aussi les modèles découverts du compte.
• Les requêtes proviennent du serveur dorsal. Dans un conteneur, localhost désigne ce conteneur, pas automatiquement l’hôte.
• Les requêtes ne suivent aucune redirection. Configurez directement l’URL finale validée.

Chat utilise le mauvais fournisseur ou en indique un comme indisponible

Le même identifiant peut exister dans Ollama et plusieurs plugins. Les sessions et préférences actuelles enregistrent le fournisseur choisi avec l’identifiant brut ; les entrées de même nom restent donc indépendantes.

• Si le sélecteur indique qu’un fournisseur est indisponible, réactivez ou réinstallez ce plugin précis et vérifiez que sa correspondance contient toujours l’identifiant enregistré.
• Si le fournisseur ou modèle a été supprimé volontairement, sélectionnez explicitement son remplaçant. Libre WebUI ne redirige pas une sélection exacte vers un modèle homonyme.
• Les anciennes sessions et préférences peuvent ne contenir aucune métadonnée de fournisseur. Elles conservent le routage historique par nom, car Libre WebUI ne peut pas deviner l’intention d’origine. Elles apparaissent comme « fournisseur non enregistré ». Resélectionnez l’entrée Ollama ou plugin souhaitée pour fixer les requêtes futures.
• Les personas restent libellés persona:<id>. Les nouvelles sélections enregistrent Ollama comme fournisseur sous-jacent ; les sessions historiques sans métadonnée restent compatibles avec l’ancien routage.

Problèmes avec Work

Work manque ou signale l’environnement indisponible

Work exige un compte actuellement authentifié disposant de l’accès : un administrateur ou tout utilisateur actif après ouverture à tout le monde dans l’onglet Gestion des utilisateurs des Paramètres. Son environnement de conteneurs doit être accessible au serveur dorsal :

docker info
docker version

Pour Docker par défaut, vérifiez qu’il fonctionne et que l’utilisateur du système qui exécute Libre WebUI peut appeler la commande WORK_DOCKER_COMMAND. Installer Libre WebUI avec npx n’installe pas Docker. Si l’environnement manque, le reste de l’application reste disponible et Libre WebUI n’exécute jamais les commandes du modèle directement sur l’hôte.

Les fichiers Compose du dépôt activent Work en montant le socket Docker de l’hôte. Sous Kubernetes, activez l’environnement natif pods/PVC avec work.enabled=true dans Helm ; ne montez pas le socket d’un nœud. Si Compose indique encore Environnement indisponible, la page Work précise le cas :

Message	Cause et solution
The "docker" CLI is not installed…	Image personnalisée sans docker-cli. Utilisez l’image officielle ou définissez WORK_DOCKER_COMMAND sur un CLI.
No Docker daemon is reachable…	Montage retiré ou démon hôte arrêté. Restaurez le montage Compose et démarrez Docker.
The Docker socket is mounted but…cannot open	Le groupe diffère de celui du conteneur. Définissez DOCKER_GID dans .env et recréez le conteneur.
L’écran ou l’audio de Work se ferme avec le code WebSocket 1006 et journalise screen is unreachable	Le backend conteneurisé appelle sa propre boucle locale. Sous Docker Desktop, gardez la valeur fournie WORK_DOCKER_PUBLISHED_HOST=host.docker.internal ; sous Docker Engine natif, définissez en plus WORK_PREVIEW_BIND sur la passerelle non publique du pont Docker, puis recréez Libre WebUI.

Lisez le groupe du socket depuis un conteneur, car macOS indique une autre valeur :

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

Ce socket accorde un contrôle de l’hôte Docker équivalent à celui de l’utilisateur racine ; consultez Work : espaces de travail isolés pour comprendre l’incidence sur votre déploiement.

Le modèle ne prend pas en charge les outils

Work exige un modèle de discussion capable d’appeler des outils. Pour Ollama, choisissez un modèle installé dont les capacités annoncées comprennent tools. Pour un modèle fourni par un plugin :

• vérifiez que le plugin de discussion ou de complétion est actif ;
• vérifiez que le modèle figure dans sa liste configurée ;
• vérifiez qu’une clé d’API est disponible pour l’administrateur actuel ;
• vérifiez que ce modèle précis accepte les appels d’outils.

Libre WebUI ne redirige jamais silencieusement une exécution échouée vers un autre fournisseur.

Une requête Work renvoie HTTP 429

L’instance a atteint une limite d’admission des tâches ou environnements actifs. Par défaut, Libre WebUI autorise deux tâches avec conteneur dans l’instance et une par utilisateur. Un aperçu actif occupe lui aussi une capacité. Attendez la fin de l’autre opération, arrêtez un aperçu inutilisé ou demandez à l’opérateur de vérifier WORK_MAX_ACTIVE_RUNTIMES_* et WORK_MAX_TASKS_*.

Échec de l’installation de paquets ou de l’accès réseau

Les nouvelles tâches utilisent un pont Docker afin que les projets générés téléchargent leurs paquets et lancent leurs aperçus. Vérifiez le DNS et le proxy Docker, la disponibilité du registre et la sortie de la commande sous Activité. Libre WebUI ne monte pas les clés SSH, identifiants cloud, profils de navigateur ou socket Docker de l’hôte dans le conteneur de tâche.

Un aperçu Work ne démarre pas

• Vérifiez que le serveur écoute sur 0.0.0.0 et WORK_PREVIEW_PORT (4173 par défaut).
• Laissez la commande facultative vide pour détecter automatiquement un script dev de package.json ou un simple index.html, y compris dans une application imbriquée unique.
• Si Work détecte plusieurs applications ou aucun point d’entrée compatible, saisissez la commande de développement explicite du projet. Elle démarre dans /workspace ; utilisez cd <app-directory> && ... pour une application imbriquée.
• Développez les détails de l’erreur pour consulter la sortie de démarrage.
• Arrêtez l’aperçu existant avant de lancer une autre commande qui exige le conteneur.

Les URL d’aperçu utilisent un port de bouclage attribué dynamiquement. Le navigateur et le serveur dorsal doivent donc s’exécuter sur la même machine. Un navigateur connecté à un serveur distant ne peut pas joindre son aperçu sur bouclage, et une page HTTPS peut bloquer un aperçu HTTP comme contenu mixte.

Impossible d’ouvrir ou d’enregistrer un fichier

L’API de fichiers Work accepte les fichiers texte UTF-8 de 2 MB au maximum. Si un fichier a changé après son ouverture, rechargez-le avant de l’enregistrer pour ne pas écraser la version récente. Le formatage est limité aux types pris en charge de moins de 100,000 caractères et 4,000 lignes ; la coloration syntaxique s’interrompt pour les fichiers volumineux afin que l’édition reste fluide.

Les modifications non enregistrées restent sous forme de brouillon dans le navigateur actuel. Elles ne remplacent pas l’enregistrement dans l’espace persistant.

Une tâche ou un aperçu a été arrêté

Arrêter une exécution ou un aperçu, ou redémarrer Libre WebUI, arrête les processus jetables du conteneur mais conserve le volume nommé de l’espace de travail. Rouvrez la tâche et relancez son aperçu. La suppression est différente : après confirmation, elle retire définitivement la tâche et son espace.

Problèmes de connexion et d’inscription

Le premier utilisateur n’est pas administrateur

Seul le premier compte créé dans une nouvelle base devient administrateur. Les bases existantes conservent leurs utilisateurs et rôles.

Erreurs JWT

Définissez un secret stable en production :

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

Modifier JWT_SECRET invalide les sessions existantes.

Turnstile bloque l’inscription

Turnstile n’est activé que si les deux clés sont présentes :

TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...

Si l’inscription échoue soudainement, vérifiez que la clé de site correspond au domaine et que la clé secrète est valide.

Échec des redirections OAuth

Définissez les URL de rappel dans le tableau de bord du fournisseur et le fichier .env du serveur dorsal :

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

Problèmes de discussion documentaire

Libre WebUI accepte les fichiers PDF, Office (DOCX/PPTX/XLSX), Markdown, HTML, de code et CSV jusqu’à 10 MB.

Si la recherche fonctionne, mais pas la récupération sémantique :

1. Installez un modèle de plongement comme nomic-embed-text.
2. Activez les plongements dans les paramètres.
3. Régénérez-les depuis les paramètres des documents ou l’API.

ollama pull nomic-embed-text

La recherche par mots-clés reste disponible si les plongements sont désactivés.

Problèmes d’aperçu des artefacts

Pour les jeux ou le HTML interactif, demandez au modèle un fichier HTML autonome complet avec CSS et JavaScript intégrés.

Si l’artefact exige une saisie au clavier :

• cliquez d’abord dans l’aperçu ;
• utilisez Ouvrir pour l’exécuter dans son propre onglet ;
• ne dépendez pas de fichiers locaux absents de la réponse.

Libre WebUI peut regrouper les blocs de code courants index.html + CSS + JavaScript, mais un HTML autonome reste la sortie la plus fiable.

Problèmes Docker

Le conteneur ne peut pas joindre Ollama

Utilisez le fichier Compose Ollama externe si Ollama ne se trouve pas dans la même pile :

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

Les données ne persistent pas

Montez un volume de données persistant et définissez DATA_DIR si nécessaire. La clé de chiffrement est stockée de façon persistante lorsque DATA_DIR ou le mode Docker est utilisé.

Réinitialiser les données locales

Arrêtez d’abord l’application. Sauvegardez puis supprimez le répertoire de données utilisé. Par défaut, les données de développement résident sous backend/data.

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

Redémarrez le serveur dorsal et créez un nouveau compte.

Toujours bloqué ?

Ouvrez un ticket en indiquant :

• la version et le commit de Libre WebUI ;
• la méthode d’installation ;
• le système d’exploitation ;
• la version de Node.js ;
• la version d’Ollama ;
• la version de Docker et le résultat de docker info pour les problèmes Work ;
• les journaux du serveur dorsal autour de l’échec ;
• les erreurs de la console du navigateur ;
• le modèle ou fournisseur exact utilisé ;
• la sortie d’Activité Work lorsqu’une tâche ou un aperçu échoue.