Hibaelhárítás

Kezdje a hibázó rétegnél: böngésző, frontend, backend, Ollama, provider plugin vagy telepítési hálózat.

Gyors ellenőrzések

# 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

Fejlesztéskor a frontend általában http://localhost:5173, a backend http://localhost:3001; a csomagolt npx libre-webui az appot http://localhost:8080 alatt szolgálja ki.

A Libre WebUI nem indul

Node és függőségek ellenőrzése

node --version
npm install
npm run dev

Node.js 22.22 vagy újabb szükséges.

A port már használatban van

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

Állítsa le a régi folyamatot vagy használjon másik portot.

A backend nem tud adatot írni

Beállított DATA_DIR alá, különben backend/data alá tárol. Forrásból a relatív DATA_DIR a backend könyvtárából, nem a shellből oldódik fel. Ezért DATA_DIR=./data → backend/data, DATA_DIR=./backend/data → backend/backend/data. Legyen írható. Beállítás nélkül a történelmi könyvtár marad, ha az egyetlen store. Ha mindkettőben van adat, állítsa le, mentse mindkettőt és tudatosan válasszon/migráljon; automatikus merge/copy nincs.

A health végpontok külön kezelik a futó folyamatot és a használható alkalmazást:

• /health és /health/live 200, amíg HTTP kiszolgálható; optional provider nem befolyásol.
• /health/ready 503, ha kötelező DB/schema/storage/platform dependency nincs. Optional providerre nem vár, public response nem mutat belső hibát.
• /health/deep SQLite integrity/foreign key ellenőrzést és optional provider probe-ot végez. Outage warning, nem unready. Current admin bearer token kell, nem gyakori probe-ra.

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

A böngésző nem éri el a backendet

Helyi fejlesztésnél a frontend VITE_API_BASE_URL-t használ, különben a development backendet.

Frontend .env példa:

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

VITE_WS_BASE_URL opcionális és Chat/Work terminal socket közös alapja. Absolute ws: vagy wss: URL, path prefix például wss://example.com/libre. Nincs credential, query vagy fragment. Vite változás után restart/rebuild.

Backend .env példa:

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

Telefon/LAN/Tailscale esetén ne localhost-ot használjon; laptop LAN/Tailscale IP és host binding kell:

npm run dev:host

Ez a frontendet a 8080-as porton szolgálja ki, és az API- és WebSocket-forgalmat a helyi, 3001-es porton futó backendre proxyzza. Csak a 8080-as portnak kell elérhetőnek lennie a másik eszközről. Ha a VITE_API_BASE_URL vagy a VITE_WS_BASE_URL be van állítva a frontend/.env fájlban, győződjön meg róla, hogy ezek az URL-ek elérhetők a másik eszközről, vagy távolítsa el őket, hogy a fejlesztői szerver proxyját használja.

A Chat nem streamel reverse proxy mögött

Az üzenet elmegy, válasz nem jelenik meg, console WebSocket hibát mutat. Engedje az upgrade-ot és hosszú kapcsolatot.

Beállított értéknél Origin ellenőrződik CORS_ORIGIN és BASE_URL szerint. Remotehoz legalább egy; egyik nélkül permissive local. Electron elhagyhatja Origint, de Authorizationt short-lived one-use ticketre cserél. Backend TLS és azonos network/proxy controls mögött.

Public hostname esetén engedje az origint:

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

Az nginx/Caddy példa Docker host proxyval és 8080 publikációval számol. Compose networkben upstream libre-webui:3001.

nginx

nginx explicit upgrade headers és hosszabb read timeout kell.

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

nginx -t után reload.

Caddy

Caddy reverse_proxy alapból támogat WebSocketet, extra header nélkül:

chat.example.com {
    reverse_proxy 127.0.0.1:8080
}

Traefik

Traefik is kezeli; shared networknél csak router/service labels:

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'

Későbbi drop esetén idle timeout proxy/load balancer. Traefik limitnél transport.respondingTimeouts.

Az Ollama nem észlelhető

Ellenőrizze, hogy Ollama fut

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

Egyéni Ollama URL

Backend .env:

OLLAMA_BASE_URL=http://localhost:11434

Libre Dockerben, Ollama hoston: external Compose vagy containerből elérhető OLLAMA_BASE_URL.

Modellletöltési problémák

Előbb terminalban próbálja

ollama pull gemma4:12b

Ha terminalban hibázik, a gond Libre-n kívül van.

Cloud modellek

Használja a Model Manager cloud filterét; Libre kezeli a suffixet, nincs kézi :cloud.

A felhasználó nem tölthet le modellt

Admin letilthatja normál usersnek. Ha látja, de nem telepíti, ellenőrizze admin settingset.

A Chat lassú vagy hibázik

• Kisebb modell, ollama ps, rövidebb context/max tokens, RAM/VRAM és provider key/quota ellenőrzése.

Az OpenAI képgenerálás nem elérhető

• Aktiválja bundled OpenAI-t, mentse current user keyt vagy trusted OPENAI_API_KEY fallbacket.
• Image Generation engedélyezés és GPT Image választás.
• gpt-image-2 ajánlott; régi IDs csak compatibility és deprecated.
• image_endpoint maradjon üres kompatibilis endpoint nélkül; Chat /responses vagy /chat/completions nem Image API.
• Érvényes key/quota melletti elutasításnál API organization eligibility ellenőrzése.

Current user credential vagy trusted env fallback számít; más user keye nem tesz láthatóvá modellt.

Provider endpoint problémák

Ha OpenAI-compatible provider rossz pathon kap kérést, nézze Settings → Plugins:

• Chat Completions /chat/completions, Responses /responses payloadhoz.
• API root https://provider.example/v1 Base URL-ként.
• API Path üres default vagy leading slash path.
• Legacy full endpoint elsőbbséget élvez; Base URL/API Path visszatérésnél törölje. Régi manifestdefault upgrade után ignorált. Suffix request formatot is meghatároz.

Imported JSON OpenAI Chat/Responses, Anthropic, Gemini wire formatot támogat. Proprietary payload/stream/tool/response backend adaptert igényel; endpointcsere nem fordít.

HTTP/HTTPS URL. HTTP titkosítás nélkül küld credentialt, csak trusted self-hosted gateway; TLS-nél HTTPS. Base URL nincs query/fragment, relative path nincs traversal/query/ fragment vagy repeated encoding. Unstable excessive encoding elutasítva.

Refresh ismert suffixet, pl. /responses, /models-ra cserél. Activation/refresh/ override current user endpoint/keyt használ. Key save/remove és reset frissít, unrelated generation nem. IDs userenként, JSON változatlan. Unsupported route esetén model_map.

Provider requests nem követ redirectet discovery, Chat, Work, image, embeddings, TTS esetén. Final URL kell; fail-closed nem engedi Authorizationt unvalidated destinationre.

Mid-run routing change után új run. Work megáll a következő request előtt, hogy old tool state ne replayeljen más mode/endpoint/key boundaryre.

Backendből jön, így localhost containerben a Libre container. Compose/Kubernetes service DNS, pl. http://ai-gateway:8080/v1; http://host.docker.internal:8080/v1 csak ha elérhető. HTTP private feloldásnál is plaintext.

Image availability/overrides/keys current userhez. Más account látszatánál auth ellenőrzése.

További security és ownership szabályok:

• Routinghoz admin login. Definitions/connection fields instance-managed, normál user generationt, credentialt és activationt menthet.
• Legacy endpoint/api_url: teljes API URL operation path-tal, pl. https://provider.example/v1/chat/completions. Root csak base_url mezőben, api_mode és optional api_path mellett.
• Absolute HTTP/HTTPS accepted. HTTP csak trusted self-hosted gateway, különben key/ prompt/response titkosítás nélkül.
• Üres override bundled endpoint. Explicit malformed/unsafe elutasítva, silent fallback nincs.
• Environment key csak unshadowed bundled definition trusted root/auth/capability/routing defaults mellett. Import, writable shadow és admin custom route ugyanazon account credentialjét kéri. Csak env key esetén unavailable és discovery skip.
• Pre-upgrade custom quarantine, mert nincs admin provenance. Admin re-import és user reactivation. Direct JSON edit újra quarantine; install/update flow rögzíti path/hash-t.
• Saved credential route/auth contract/definition/source binding. Változás után re-save. Old unbound csak exact anchored bundled route-on migrál.
• Imported api_url legacy alias, endpoint elsőbbség. Más discovery teljes models_endpoint, validált, redirect nélkül.
• Endpoint/credential save után activation; /models derivation és activating user credential, ha nincs models_endpoint. Connection save/reset refresh és UI megvárja. Aktiválás account-specific.
• Settings → Plugins → Refresh models. Read-only table current account IDs. Transient failure previous catalogot vagy fallback model_map-ot tart; completed check nem health proof.
• Automatic discovery OpenAI-compatible data. Catalog per user, shared JSON változatlan. Normál activation previous-t tart unavailable esetén; connection change előbb töröl, failure model_map-ot használ.
• Image model/override/key current userhez; ellenőrizze authot más account látszatánál.
• Upgraded non-admin régi routing értékén Reset, hogy role change ne aktiválja; routing save/reset discovered models-t is töröl.
• Backendből jön; containerben localhost container. Redirect nincs, final URL kell.

A Chat rossz vagy nem elérhető szolgáltatót használ

Azonos ID lehet Ollamában és pluginokban. Chat session és default preference providert és raw ID-t ment, így azonos nevek függetlenek.

• Unavailable esetén exact plugin re-activate/reinstall és model map check.
• Szándékos eltávolításnál explicit replacement; Libre nem redirectel azonos nevű más providerre.
• Régi session metadata nélkül name-only routingot tart, mert eredeti nem inferálható. "provider not recorded" jelenik meg; válassza újra Ollama/plugin elemet.
• Persona label persona:<id>; új választás Ollama backing, régi metadata nélkül compatible.

Work-problémák

A Work hiányzik vagy Runtime unavailable

Current authenticated Work account kell — admin vagy aktív user, miután admin megnyitotta. Container runtime legyen backendből elérhető:

docker info
docker version

Default Dockernél futás és OS user WORK_DOCKER_COMMAND joga. npx nem telepít Dockert. Runtime nélkül app többi része elérhető, host command fallback nincs.

Compose host socketot mountol. Kubernetesben work.enabled=true Pod/PVC, node socket soha. Runtime unavailable esetén panel megnevezi:

Üzenet	Ok és javítás
The "docker" CLI is not installed…	Custom image docker-cli nélkül. Official image vagy WORK_DOCKER_COMMAND.
No Docker daemon is reachable…	Socket mount hiányzik vagy daemon stopped. Mount vissza és Docker start.
The Docker socket is mounted but…cannot open	Socket group eltér. DOCKER_GID az .env-ben és recreate.
A Work képernyője vagy hangja 1006 WebSocket-kóddal zárul, a logban screen is unreachable	A konténerben futó backend a saját loopbackjét hívja. Docker Desktopon használja a szállított WORK_DOCKER_PUBLISHED_HOST=host.docker.internal beállítást; natív Docker Engine esetén állítsa be a WORK_PREVIEW_BIND értékét is a Docker-híd nem nyilvános átjárójára, majd hozza létre újra a Libre WebUI konténerét.

Socket groupot containeren át olvassa, mert macOS mást mutat:

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

A socket root-egyenértékű vezérlést ad a Docker host felett. Olvassa el a Work: izolált munkaterületek útmutatót a telepítési következményekről.

A modell nem támogat eszközt

Work tool-capable chatet kér. Ollama modelben tools. Pluginnál:

• Active plugin, modell a listában, admin API key és exact modell tool call support.

Failed Work nincs silent más providerre routing.

Work request HTTP 429

Task/active-runtime limit elérve. Default két global, egy user; preview is capacity. Várjon, állítsa le previewt vagy nézze WORK_MAX_ACTIVE_RUNTIMES_*, WORK_MAX_TASKS_*.

Package vagy network hiba

Új task Docker bridge-et használ package/preview miatt. DNS, proxy, registry és Activity ellenőrzése. Nincs host SSH key, cloud credential, browser profile vagy socket mount.

A Work preview nem indul

• Server bind 0.0.0.0 a WORK_PREVIEW_PORT porton (default 4173).
• Üres command autodetect package.json dev vagy index.html, egy nested appal.
• Multiple/no entry esetén explicit dev command, /workspace-ből, nestedhez cd <app-directory> && ....
• Error details inspect és meglévő preview stop másik command előtt.

Dynamic loopback port miatt browser és backend azonos machine. Remote browser nem éri el loopbacket, HTTPS blokkolhat HTTP mixed contentet.

Workspace-fájl nem nyitható vagy menthető

UTF-8 text max 2 MB. Ha megnyitás után változott, reload mentés előtt. Formatting támogatott típus 100 000 char/4 000 line alatt; highlight nagy fájlnál pause.

Unsaved edit browser draft, nem persistent save helyett.

Task vagy preview leállt

Run/preview stop vagy restart disposable processzt állít, named volume marad. Reopen és preview restart. Delete megerősítés után task/workspace végleges.

Bejelentkezési és regisztrációs problémák

Az első user nem admin

Csak friss DB első fiókja admin; meglévő DB megtart users/roles.

JWT-hibák

Productionben stabil secret:

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

JWT_SECRET változás invalidálja sessionöket.

Turnstile blokkolja a regisztrációt

Csak mindkét key mellett aktív:

TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...

Ellenőrizze site key/domain egyezést és valid secretet.

OAuth redirect hibázik

Callback URL provider dashboardban és backend .env-ben:

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

Document Chat problémák

PDF, Office, Markdown, HTML, code, CSV max 10 MB.

Ha search működik, semantic retrieval nem:

1. Telepítsen nomic-embed-text embeddinget.
2. Engedélyezze Settingsben.
3. Generálja újra document settingsből vagy API-ból.

ollama pull nomic-embed-text

Keyword search embedding nélkül is működik.

Artifact preview problémák

Játékhoz/interaktív HTML-hez kérjen egy self-contained HTML-t inline CSS/JS-sel.

Billentyűzethez:

• Előbb kattintson previewba vagy Open saját tabon; ne támaszkodjon response-ból hiányzó local files-ra.

Libre egyesíti index.html + CSS + JavaScript blokkokat, de self-contained a legbiztosabb.

Docker-problémák

A container nem éri el Ollamát

Használjon external Ollama compose-t, ha nincs ugyanabban stackben:

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

Az adat nem marad meg

Mount persistent volume és állítsa DATA_DIR-t. Encryption key persistent storage-ban marad.

Helyi adat visszaállítása

Állítsa le, mentse és törölje használt data directoryt. Default development backend/data.

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

Indítsa újra és hozzon létre új fiókot.

Továbbra is elakadt

Nyisson issue-t ezekkel:

• Libre verzió/commit, install mód, OS, Node.js/Ollama/Docker;
• docker info, backend logs, browser errors, exact model/provider és Work Activity output.