Řešení potíží

Začněte vrstvou, která selhává: prohlížeč, frontend, backend, Ollama, plugin poskytovatele nebo síť instalace.

Rychlé kontroly

# 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

Při vývoji frontend obvykle běží na http://localhost:5173 a backend na http://localhost:3001. Balíčkový postup npx libre-webui podává aplikaci na http://localhost:8080.

Libre WebUI se nespustí

Zkontrolujte Node a závislosti

node --version
npm install
npm run dev

Je vyžadován Node.js 22.22 nebo novější.

Port je již používán

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

Zastavte starý proces nebo nastavte jiný port.

Backend nemůže zapisovat data

Backend ukládá data pod DATA_DIR, pokud je nastavena, jinak v backend/data. Spuštění ze zdroje vyhodnocuje relativní DATA_DIR z adresáře backendu, ne z aktuálního adresáře shellu. Proto DATA_DIR=./data vybírá backend/data, zatímco historicky podporovaná DATA_DIR=./backend/data vybírá backend/backend/data. Ověřte možnost zápisu. Bez nastavení Libre zachová historický adresář, pokud jde o jediné úložiště. Pokud oba obsahují data, Libre zastavte, oba zazálohujte a vědomě vyberte či migrujte. Libre rozdílné databáze nikdy neslučuje ani nekopíruje.

Koncové body zdraví záměrně rozlišují běžící proces a použitelnou aplikaci:

• /health a /health/live vracejí 200, dokud backend dokáže podávat HTTP. Volitelní poskytovatelé živost neovlivňují.
• /health/ready vrací 503, pokud chybí povinná databáze, schéma, úložiště nebo závislost platformy. Na volitelné modely nečeká a veřejná odpověď vynechá chybové zprávy a interní podrobnosti.
• /health/deep provádí omezeným workerem integritu a cizí klíče SQLite a agreguje volitelné sondy serverových poskytovatelů jako Ollama. Výpadek volitelného zdroje je varování a neznepřístupní povinné závislosti. Koncový bod vyžaduje aktuální bearer token správce a nehodí se pro častou sondu orchestrátoru.

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

Prohlížeč se nedostane k backendu

Pro místní vývoj frontend používá nastavenou VITE_API_BASE_URL, jinak vývojový backend.

Příklad .env frontendu:

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

VITE_WS_BASE_URL je volitelná, ale po nastavení tvoří společný základ socketů Chat a terminálu Work. Použijte absolutní URL ws: nebo wss:; podporuje se předpona cesty jako wss://example.com/libre. Nezahrnujte přihlašovací údaje, parametry dotazu ani fragmenty. Po změně proměnné Vite frontend restartujte nebo znovu sestavte.

Příklad .env backendu:

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

Pro přístup z telefonu, LAN či Tailscale nesměrujte telefon na localhost. Použijte LAN nebo Tailscale IP notebooku a spusťte vývojový server s vazbou hostitele:

npm run dev:host

Tento příkaz obsluhuje frontend na portu 8080 a přeposílá provoz API a WebSocket na lokální backend na portu 3001. Z druhého zařízení musí být dostupný pouze port 8080. Pokud je v frontend/.env nastaveno VITE_API_BASE_URL nebo VITE_WS_BASE_URL, ujistěte se, že tyto adresy jsou z druhého zařízení dostupné, nebo je odeberte a použijte proxy vývojového serveru.

Chat nestreamuje za reverse proxy

Typickým příznakem je odeslání zprávy bez vykreslení odpovědi a chyba WebSocket v konzoli. Ověřte, že proxy dovoluje upgrade WebSocket a nezavírá dlouhá spojení.

Při nastavení jedné hodnoty se upgrade s hlavičkou Origin porovná s CORS_ORIGIN a BASE_URL. Pro vzdálenou instalaci nastavte alespoň jednu; bez obou je filtr při místním vývoji povolující. Electron a další klienti mohou Origin vynechat, ale musí nejprve vyměnit Authorization za krátkodobý jednorázový ticket. Backend držte za TLS a stejnými síťovými či proxy kontrolami jako HTTP API.

Pro veřejný název povolte origin prohlížeče ve službě Libre WebUI:

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

Příklady nginx a Caddy předpokládají proxy na hostiteli Docker, kde Compose publikuje Libre WebUI na portu 8080. Pokud proxy vstoupí do sítě Compose, použijte upstream libre-webui:3001.

nginx

nginx vyžaduje výslovné přeposlání upgrade hlaviček. Delší časový limit čtení drží nečinné spojení otevřené během práce modelu.

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

Po ověření přes nginx -t nginx znovu načtěte.

Caddy

reverse_proxy Caddy podporuje WebSocket přímo, takže upgrade hlavičky nejsou potřeba:

chat.example.com {
    reverse_proxy 127.0.0.1:8080
}

Traefik

Traefik také upgrade řeší automaticky. Když jeho Docker provider sdílí síť Libre WebUI, stačí běžné štítky směrovače a služby:

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'

Pokud se proudy připojí a později vypadnou, zkontrolujte čas nečinnosti proxy či load balanceru před Traefik. Pokud limit vynucuje sám, upravte transport.respondingTimeouts vstupního bodu.

Ollama nebyla rozpoznána

Ověřte, že Ollama běží

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

Nastavte vlastní URL Ollama

.env backendu:

OLLAMA_BASE_URL=http://localhost:11434

Pokud Libre WebUI běží v Dockeru a Ollama na hostiteli, použijte Compose pro externí Ollama nebo nastavte OLLAMA_BASE_URL na adresu hostitele dosažitelnou z kontejneru.

Problémy se stahováním modelů

Nejprve stáhněte v terminálu

ollama pull gemma4:12b

Pokud stažení v terminálu selže, problém je mimo Libre WebUI.

Cloudové modely

Pro Ollama Cloud použijte cloudový filtr Model Manager. Libre WebUI přípony normalizuje, takže uživatelé nemusí ručně přidávat :cloud.

Uživatel nemůže stahovat modely

Správci mohou běžným uživatelům zakázat stahování. Pokud uživatel modely vidí, ale nenainstaluje, zkontrolujte nastavení správce.

Chat je pomalý nebo selhává

• Použijte menší model.
• Zkontrolujte načtené modely přes ollama ps.
• Zkraťte kontext.
• U dlouhých odpovědí snižte maximum tokenů.
• Ověřte, že se model vejde do RAM/VRAM.
• U pluginů ověřte klíč API a kvótu poskytovatele.

Generování obrázků OpenAI není dostupné

• Zapněte vestavěný OpenAI. Uložte klíč aktuálního uživatele nebo nastavte OPENAI_API_KEY jako fallback důvěryhodné vestavěné definice.
• V Image Generation zapněte obrázky a vyberte nabízený model GPT Image.
• Upřednostněte gpt-image-2. Starší ID jsou jen pro kompatibilitu a upstream je nedoporučuje.
• Nechte přepsání image_endpoint prázdné, pokud neprovozujete kompatibilní bod. Chat /responses ani /chat/completions požadavky Image API nezpracuje.
• Při odmítnutí navzdory klíči a kvótě ověřte způsobilost organizace používat GPT Image.

Dostupnost obrázků se vyhodnocuje s údaji aktuálního uživatele nebo fallbackem důvěryhodného poskytovatele. Klíč jiného uživatele modely nezpřístupní.

Problémy koncových bodů poskytovatelů

Pokud OpenAI-kompatibilní poskytovatel dostává požadavky na nesprávné cestě, zkontrolujte Settings → Plugins:

• Chat Completions zvolte pro /chat/completions, Responses pro /responses.
• Jako Base URL zadejte kořen API, například https://provider.example/v1.
• API Path nechte prázdnou pro výchozí cestu nebo zadejte cestu poskytovatele s lomítkem.
• Skutečný starší úplný koncový bod má nejvyšší prioritu; při návratu na Base URL a API Path ho vymažte. Hodnoty rovné starému výchozímu manifestu se po upgradu ignorují. Přípona /chat/completions nebo /responses také určuje formát požadavku.

Importovaný JSON podporuje komunikační formáty OpenAI Chat Completions, Responses, Anthropic a Gemini. Vlastní payload, stream, nástroje či odpověď potřebují adaptér backendu; samotná změna koncového bodu formát nepřeloží.

URL poskytovatelů mohou být HTTP nebo HTTPS. HTTP posílá údaje a provoz bez šifrování, proto patří jen vlastní bráně v důvěryhodné síti; při TLS preferujte HTTPS. Base URL nesmí mít dotaz ani fragment a relativní cesty nesmí obsahovat traversal segmenty, dotazy, fragmenty ani jejich opakované kódování. Nestabilní nadměrné kódování se odmítne.

Obnovení modelů nahradí známé přípony včetně /responses za /models. Aktivace, obnovení a přepsání používají koncový bod a klíč aktuálního uživatele. Uložení či odebrání klíče a reset připojení seznam také obnoví, nesouvisející generování nikoli. ID se ukládají pro uživatele a nepřepisují JSON. Nepodporuje-li poskytovatel odvozenou trasu, nastavte ID ručně v model_map.

Požadavky poskytovatele záměrně nenásledují přesměrování pro modely, Chat, Work, obrázky, embeddingy ani TTS. Nastavte konečnou URL. Fail-closed zabrání přesunu autorizační hlavičky na neověřenou destinaci.

Pokud Work oznámí změnu směrování během běhu, po dokončení nastavení zahajte nový běh. Work se zastaví před dalším požadavkem, aby se stav nástrojů nepřehrál do jiné hranice režimu, bodu či klíče.

Požadavky vznikají v backendu, proto localhost v kontejneru znamená kontejner Libre WebUI, ne hostitele. V Compose či Kubernetes použijte DNS služby, například http://ai-gateway:8080/v1. http://host.docker.internal:8080/v1 jen pokud ho běh zpřístupňuje. HTTP je otevřený text i na soukromé adrese.

Dostupnost obrazových modelů, přepsání a klíče se také řeší pro aktuálního uživatele. Pokud požadavek používá zdánlivě jiný účet, ověřte identitu požadavku.

Platí také tato pravidla zabezpečení a vlastnictví:

• Směrování mění přihlášený správce. Definice a pole připojení jsou konfigurací instance; běžní uživatelé ukládají generování, údaje a vlastní aktivaci.
• U staršího endpoint nebo api_url zadejte úplnou URL včetně cesty, například https://provider.example/v1/chat/completions. Kořen patří jen do base_url s api_mode a volitelnou api_path.
• Absolutní HTTP a HTTPS jsou přijímány. HTTP jen pro vlastní bránu v důvěryhodné síti, jinak klíče, prompty a odpovědi putují bez šifrování.
• Prázdné přepsání používá vestavěný bod. Výslovně neplatné či nebezpečné se odmítne; Libre požadavek potichu neposílá na výchozího poskytovatele.
• Klíč prostředí se použije jen při nezastíněné vestavěné definici s důvěryhodným kořenem, ověřovacími poli, body a výchozími proměnnými. Importy, zapisovatelné definice se stejným ID a vlastní trasy správce vyžadují údaje stejného účtu. Jen s klíčem prostředí je poskytovatel záměrně nedostupný a hledání se přeskočí.
• Vlastní definice před upgradem jsou v karanténě, protože starší verze neukládaly provenienci. Správce je musí znovu importovat a uživatelé aktivovat. Přímá úprava schváleného JSON karanténu obnoví; používejte instalační či aktualizační postup správce.
• Údaje jsou svázány s trasou, smlouvou, definicí a zdrojem při uložení. Po změně je uložte znovu. Starší nevázané údaje se migrují jen na přesně ukotvené vestavěné trase.
• Plugin může používat api_url jako starší alias. Při obou má přednost endpoint. Jiné hledání nastavte úplnou URL v models_endpoint; ověří se a nepřesměrovává.
• Po uložení bodu a údajů plugin aktivujte. Aktivace odvodí /models a použije údaje aktivujícího uživatele, pokud není models_endpoint. Uložení či reset polí také obnoví hledání a čeká na něj před načtením UI. Každý účet aktivuje plugin zvlášť.
• V Settings → Plugins vyberte poskytovatele a Refresh models. Tabulka je jen pro čtení a ukazuje ID účtu. Dočasné selhání zachová minulý katalog nebo záložní model_map; dokončená kontrola sama nedokazuje zdraví vzdáleného bodu.
• Automatické hledání vyžaduje OpenAI-kompatibilní pole data. Katalogy se ukládají pro uživatele bez změny sdíleného JSON. Běžná aktivace zachová starý katalog, změna připojení ho nejprve smaže, takže při selhání použije model_map pluginu.
• Obrazové modely, přepsání a klíče se řeší pro aktuálního uživatele. Při zdánlivě jiném účtu ověřte identitu požadavku.
• Pokud účet bez správce dříve uložil trasu, použijte Reset. Ignorovaná hodnota se odstraní, aby se po změně role nevrátila. Uložení/reset také smaže staré modely.
• Požadavky vznikají v backendu; localhost v kontejneru označuje kontejner.
• Požadavky poskytovatele nenásledují přesměrování. Nastavte konečnou ověřenou URL.

Chat používá nesprávného nebo nedostupného poskytovatele

Stejné ID může být v Ollama a více pluginech. Relace Chat a výchozí předvolby ukládají poskytovatele i surové ID, takže podobné názvy jsou nezávislé volby.

• Při nedostupnosti znovu aktivujte či nainstalujte přesný plugin a ověřte ID v mapě.
• Při úmyslném odstranění výslovně vyberte náhradu. Libre nepřesměruje uloženou volbu na stejně pojmenovaný model jiného poskytovatele.
• Starší relace mohou postrádat metadata a kvůli nemožnosti určit původní zdroj používat starší směrování jen podle názvu. Zobrazí se jako "provider not recorded". Novým výběrem Ollama či pluginu připněte budoucí požadavky.
• Persona zůstává persona:<id>. Nové volby zapisují Ollama jako podklad; historické relace bez metadata zůstávají kompatibilní.

Problémy Work

Work chybí nebo hlásí Runtime unavailable

Work vyžaduje aktuálně ověřený účet s přístupem — správce nebo aktivního uživatele, pokud správce otevřel Work všem na kartě User Management v Settings. Běh kontejnerů musí být dostupný backendu:

docker info
docker version

U výchozího Docker backendu ověřte běh Docker a oprávnění uživatele operačního systému volat WORK_DOCKER_COMMAND. Instalace přes npx Docker neinstaluje. Bez běhu zůstane zbytek aplikace dostupný a příkazy se nespustí na hostiteli.

Soubory Compose zapínají Work připojením socketu hostitele. V Kubernetes zapněte nativní Pod/PVC přes work.enabled=true; nepřipojujte socket uzlu. Pokud Compose stále hlásí Runtime unavailable, stránka určí příčinu:

Zpráva	Příčina a řešení
The "docker" CLI is not installed…	Vlastní image bez docker-cli. Použijte oficiální image nebo nastavte WORK_DOCKER_COMMAND.
No Docker daemon is reachable…	Socket není připojen nebo démon neběží. Obnovte mount v Compose a spusťte Docker.
The Docker socket is mounted but…cannot open	Skupina socketu nesouhlasí. Nastavte DOCKER_GID v .env a kontejner znovu vytvořte.
Obrazovka nebo zvuk Work se zavře s WebSocketem 1006 a v logu je screen is unreachable	Backend v kontejneru volá vlastní loopback. Na Docker Desktopu použijte dodávané WORK_DOCKER_PUBLISHED_HOST=host.docker.internal; na nativním Docker Engine navíc nastavte WORK_PREVIEW_BIND na neveřejnou bránu mostu Docker a Libre WebUI znovu vytvořte.

Skupinu socketu čtěte přes kontejner, protože macOS hlásí jinou hodnotu než kontejner:

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

Tento socket poskytuje nad hostitelem Docker oprávnění odpovídající root. Dopady popisuje Work: Izolované pracovní prostory.

Model nepodporuje nástroje

Work vyžaduje chatový model s nástroji. U Ollama vyberte nainstalovaný model s funkcí tools. U pluginu:

• Ověřte aktivaci pluginu chatu nebo dokončování.
• Ověřte model v jeho seznamu.
• Ověřte klíč API aktuálního správce.
• Ověřte nástroje u přesného modelu.

Libre WebUI neúspěšný běh potichu nesměruje jinam.

Požadavek Work vrací HTTP 429

Instance dosáhla limitu úloh nebo aktivních běhů. Výchozí jsou dvě kontejnerové úlohy v instanci a jedna na uživatele; náhled také zabírá kapacitu. Počkejte, zastavte nepoužívaný náhled nebo zkontrolujte WORK_MAX_ACTIVE_RUNTIMES_* a WORK_MAX_TASKS_*.

Selže instalace balíčku nebo síť

Nové úlohy používají bridge síť Docker pro balíčky a náhledy. Zkontrolujte DNS, proxy, registry a výstup v Activity. Libre nepřipojuje klíče SSH, cloudové údaje, profily prohlížeče ani socket do kontejneru úlohy.

Náhled Work se nespustí

• Server musí vázat 0.0.0.0 na WORK_PREVIEW_PORT (výchozí 4173).
• Prázdný příkaz automaticky najde skript dev v package.json nebo index.html, včetně jedné vnořené aplikace.
• Při více aplikacích nebo bez vstupu zadejte vývojový příkaz. Začíná v /workspace, pro vnoření použijte cd <app-directory> && ....
• Rozbalte podrobnosti chyby a zkontrolujte výstup.
• Před jiným příkazem potřebujícím kontejner zastavte náhled.

URL náhledu používají dynamický loopback port, proto musí prohlížeč a backend běžet na stejném stroji. Prohlížeč vzdáleného backendu jeho loopback nedosáhne a HTTPS může HTTP náhled blokovat jako smíšený obsah.

Soubor prostoru nelze otevřít nebo uložit

API přijímá UTF-8 texty do 2 MB. Pokud se otevřený soubor změnil, před uložením ho načtěte znovu. Formátování je pro podporované typy do 100 000 znaků a 4 000 řádků; zvýraznění se u velkých souborů pozastaví.

Neuložené úpravy jsou konceptem v prohlížeči, nikoli náhradou trvalého uložení.

Úloha nebo náhled byly zastaveny

Zastavení běhu, náhledu nebo restart aplikace ukončí dočasné procesy, ale zachová pojmenovaný svazek. Úlohu znovu otevřete a náhled spusťte. Smazání po potvrzení trvale odstraní úlohu i prostor.

Problémy přihlášení a registrace

První uživatel není správce

Správcem se stane pouze první účet nové databáze. Existující databáze zachovají uživatele a role.

Chyby JWT

V produkci nastavte stabilní tajemství:

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

Změna JWT_SECRET zneplatní relace.

Turnstile blokuje registraci

Turnstile se zapne pouze s oběma klíči:

TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...

Při náhlém selhání ověřte shodu site klíče s doménou a platnost tajného klíče.

Přesměrování OAuth selže

Nastavte callback URL v panelu poskytovatele i .env backendu:

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émy Document Chat

Libre WebUI přijímá PDF, Office (DOCX/PPTX/XLSX), Markdown, HTML, kód a CSV do 10 MB.

Pokud hledání funguje, ale sémantické načítání ne:

1. Nainstalujte model embeddingů jako nomic-embed-text.
2. Zapněte embeddingy v Settings.
3. Znovu je vytvořte z nastavení dokumentu nebo API.

ollama pull nomic-embed-text

Klíčová slova fungují i s vypnutými embeddingy.

Problémy náhledu artefaktů

Pro hry či interaktivní HTML požádejte o jeden samostatný soubor s vloženými CSS a JavaScript.

Pokud artefakt potřebuje klávesnici:

• Nejprve klikněte do náhledu.
• Tlačítkem Open ho spusťte ve vlastní kartě.
• Nespoléhejte na místní soubory, které nebyly v odpovědi.

Libre WebUI umí spojit index.html + CSS + JavaScript, ale samostatné HTML je nejspolehlivější.

Problémy Docker

Kontejner nedosáhne Ollama

Pokud Ollama není ve stejném stacku, použijte Compose pro externí Ollama:

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

Data nepřetrvávají

Připojte trvalý svazek a případně nastavte DATA_DIR. V Dockeru či s DATA_DIR se šifrovací klíč ukládá trvale.

Reset místních dat

Nejprve aplikaci zastavte, zazálohujte a odstraňte používaný datový adresář. Vývojový je výchozí backend/data.

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

Restartujte backend a vytvořte nový účet.

Stále bez řešení

Otevřete issue s údaji:

• Verze a commit Libre WebUI
• Způsob instalace
• Operační systém
• Verze Node.js, Ollama a Docker
• Výstup docker info u Work
• Protokoly backendu kolem chyby
• Chyby konzole
• Přesný model a poskytovatel
• Výstup Work Activity u selhání