Αντιμετώπιση προβλημάτων

Ξεκινήστε από το επίπεδο που αποτυγχάνει: browser, frontend, backend, Ollama, plugin παρόχου ή δίκτυο εγκατάστασης.

Γρήγοροι έλεγχοι

# 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

Στην ανάπτυξη, το frontend συνήθως τρέχει στο http://localhost:5173 και το backend στο http://localhost:3001. Η packaged ροή npx libre-webui σερβίρει στο http://localhost:8080.

Το Libre WebUI δεν ξεκινά

Ελέγξτε Node και dependencies

node --version
npm install
npm run dev

Απαιτείται Node.js 22.22 ή νεότερο.

Η θύρα χρησιμοποιείται ήδη

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

Σταματήστε την παλιά διεργασία ή ορίστε άλλη θύρα.

Το backend δεν γράφει δεδομένα

Το backend αποθηκεύει στο DATA_DIR, αλλιώς backend/data. Η εκκίνηση από source επιλύει σχετικό DATA_DIR από τον κατάλογο backend, όχι τον τρέχοντα shell. Έτσι DATA_DIR=./data σημαίνει backend/data, ενώ DATA_DIR=./backend/data σημαίνει backend/backend/data. Ο κατάλογος πρέπει να είναι εγγράψιμος. Χωρίς τιμή, το Libre κρατά τον ιστορικό κατάλογο όταν είναι η μόνη αποθήκη. Αν και οι δύο έχουν δεδομένα, σταματήστε, αντιγράψτε και επιλέξτε ή μεταφέρετε σκόπιμα· ποτέ δεν συγχωνεύει διαφορετικές βάσεις.

Τα health endpoints ξεχωρίζουν σκόπιμα running process και usable εφαρμογή:

• /health και /health/live επιστρέφουν 200 όσο το backend σερβίρει HTTP. Προαιρετικοί πάροχοι δεν επηρεάζουν liveness.
• /health/ready επιστρέφει 503 όταν απαιτούμενη βάση, schema, storage ή registered dependency δεν είναι διαθέσιμη. Δεν περιμένει optional providers και η public απόκριση παραλείπει errors/details.
• /health/deep ελέγχει integrity και foreign keys SQLite σε bounded worker και συγκεντρώνει optional probes όπως Ollama. Outage εμφανίζεται warning χωρίς να κάνει required dependencies unready. Απαιτεί current admin bearer token και δεν είναι για συχνό probe.

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

Ο browser δεν φτάνει το backend

Για τοπική ανάπτυξη το frontend χρησιμοποιεί VITE_API_BASE_URL όταν ορίζεται, αλλιώς development backend.

Παράδειγμα frontend .env:

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

Το VITE_WS_BASE_URL είναι προαιρετικό και γίνεται κοινή βάση για Chat και Work terminal sockets. Χρησιμοποιήστε absolute ws: ή wss:· υποστηρίζεται prefix όπως wss://example.com/libre. Χωρίς credentials, query params ή fragments. Μετά αλλαγή Vite variable κάντε restart/rebuild.

Παράδειγμα backend .env:

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

Για phone/LAN/Tailscale, μην δείχνετε το τηλέφωνο στο localhost. Χρησιμοποιήστε IP του laptop και host binding:

npm run dev:host

Αυτό εξυπηρετεί το frontend στη θύρα 8080 και προωθεί την κίνηση API και WebSocket στο τοπικό backend στη θύρα 3001. Μόνο η θύρα 8080 χρειάζεται να είναι προσβάσιμη από την άλλη συσκευή. Αν έχει οριστεί το VITE_API_BASE_URL ή το VITE_WS_BASE_URL στο frontend/.env, βεβαιωθείτε ότι αυτές οι URL είναι προσβάσιμες από την άλλη συσκευή ή αφαιρέστε τις για να χρησιμοποιηθεί ο proxy του dev server.

Το Chat δεν κάνει stream πίσω από reverse proxy

Τυπικά το μήνυμα στέλνεται αλλά απάντηση δεν εμφανίζεται και console δείχνει WebSocket failure. Επιβεβαιώστε upgrades και ότι proxy δεν κλείνει long-lived connections.

Με ορισμένη τιμή, upgrades με Origin ελέγχονται έναντι CORS_ORIGIN και BASE_URL. Ορίστε τουλάχιστον μία για remote· χωρίς καμία, το filter είναι permissive τοπικά. Electron μπορεί να παραλείψει Origin, αλλά ανταλλάσσει Authorization για short-lived one-use ticket. Κρατήστε backend πίσω από TLS και ίδια network/proxy controls με HTTP API.

Για public hostname επιτρέψτε το origin στην υπηρεσία Libre WebUI:

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

Τα παραδείγματα nginx/Caddy θεωρούν proxy στον Docker host, όπου Compose δημοσιεύει θύρα 8080. Αν μπει στο Compose network, upstream libre-webui:3001.

nginx

Το nginx απαιτεί ρητά upgrade headers. Μεγαλύτερο read timeout κρατά σύνδεση όσο εργάζεται το μοντέλο.

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

Κάντε reload nginx μετά nginx -t.

Caddy

Το reverse_proxy του Caddy υποστηρίζει WebSockets χωρίς επιπλέον headers:

chat.example.com {
    reverse_proxy 127.0.0.1:8080
}

Traefik

Το Traefik χειρίζεται upgrades. Όταν ο Docker provider μοιράζεται το δίκτυο, χρειάζονται μόνο 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'

Αν stream συνδέεται και πέφτει, ελέγξτε idle timeout proxy/load balancer. Αν το Traefik επιβάλλει, ρυθμίστε transport.respondingTimeouts.

Το Ollama δεν ανιχνεύεται

Επιβεβαιώστε ότι Ollama τρέχει

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

Ρυθμίστε custom Ollama URL

Backend .env:

OLLAMA_BASE_URL=http://localhost:11434

Αν Libre είναι Docker και Ollama host, χρησιμοποιήστε external compose ή OLLAMA_BASE_URL σε reachable host address.

Προβλήματα λήψης μοντέλων

Δοκιμάστε πρώτα από terminal

ollama pull gemma4:12b

Αν αποτύχει στο terminal, το πρόβλημα είναι εκτός Libre WebUI.

Cloud μοντέλα

Χρησιμοποιήστε cloud filter στο Model Manager. Το Libre κανονικοποιεί suffix, χωρίς χειροκίνητο :cloud.

Ο χρήστης δεν μπορεί να κατεβάσει μοντέλα

Οι admins μπορούν να απενεργοποιήσουν λήψεις για κανονικούς χρήστες. Αν βλέπει αλλά δεν εγκαθιστά, ελέγξτε admin settings.

Το Chat είναι αργό ή αποτυγχάνει

• Μικρότερο μοντέλο, έλεγχος ollama ps, μικρότερο context και max tokens.
• Επιβεβαιώστε ότι χωρά RAM/VRAM και, για plugin, API key και quota.

Η δημιουργία εικόνας OpenAI δεν είναι διαθέσιμη

• Ενεργοποιήστε bundled OpenAI και αποθηκεύστε key τρέχοντος χρήστη ή fallback OPENAI_API_KEY της trusted definition.
• Στο Image Generation ενεργοποιήστε και επιλέξτε GPT Image.
• Προτιμήστε gpt-image-2. Παλιά IDs είναι μόνο για compatibility και deprecated upstream.
• Κρατήστε image_endpoint κενό εκτός αν έχετε συμβατό endpoint. Chat /responses ή /chat/completions δεν επεξεργάζεται Image API.
• Αν απορριφθεί με έγκυρο key/quota, επιβεβαιώστε eligibility του API organization.

Η διαθεσιμότητα αξιολογείται με credential τρέχοντος χρήστη ή trusted environment fallback. Key άλλου χρήστη δεν εκθέτει image models.

Προβλήματα endpoint παρόχου

Αν OpenAI-compatible πάροχος λαμβάνει λάθος path, ελέγξτε Settings → Plugins:

• Chat Completions για /chat/completions, Responses για /responses.
• API root όπως https://provider.example/v1 ως Base URL.
• Κενό API Path για default ή path με αρχικό slash.
• Legacy full endpoint έχει υψηλότερη προτεραιότητα· καθαρίστε το όταν επιστρέφετε σε Base URL/API Path. Παλιά default manifest values αγνοούνται μετά upgrade. Suffix /chat/completions ή /responses καθορίζει request format.

Imported JSON υποστηρίζει wire formats OpenAI Chat Completions, Responses, Anthropic, Gemini. Proprietary payload/stream/tool/response χρειάζεται backend adapter· endpoint μόνο δεν μεταφράζει.

URLs μπορεί HTTP/HTTPS. HTTP στέλνει credentials χωρίς transport encryption, μόνο σε trusted self-hosted gateway· προτιμήστε HTTPS με TLS. Base URL χωρίς query/fragment και relative API path χωρίς traversal, query, fragment ή repeated encoding. Unstable excessive encoding απορρίπτεται.

Refresh αντικαθιστά γνωστά suffix όπως /responses με /models. Activation, refresh και overrides χρησιμοποιούν endpoint/key τρέχοντος χρήστη. Save/remove key και reset ανανεώνουν, άσχετες generation params όχι. IDs αποθηκεύονται ανά χρήστη χωρίς overwrite JSON. Αν route δεν υποστηρίζεται, ορίστε IDs στο model_map.

Provider requests δεν ακολουθούν redirects σε discovery, Chat, Work, image, embeddings, TTS. Ρυθμίστε final URL. Fail-closed εμποδίζει Authorization να πάει σε unvalidated destination.

Αν Work αναφέρει αλλαγή routing mid-run, ξεκινήστε νέο run μετά το update. Σταματά πριν το επόμενο provider request ώστε παλιό tool state να μη replayάρει σε άλλο mode/endpoint/key boundary.

Τα αιτήματα προέρχονται από backend, άρα localhost σε container είναι το Libre container. Σε Compose/Kubernetes χρησιμοποιήστε service DNS π.χ. http://ai-gateway:8080/v1. http://host.docker.internal:8080/v1 μόνο όταν εκτίθεται. HTTP παραμένει plaintext και σε private resolution.

Image availability, overrides και keys επιλύονται για current user. Αν φαίνεται άλλος account, ελέγξτε authentication του request.

Ισχύουν επίσης οι παρακάτω κανόνες ασφάλειας και ιδιοκτησίας:

• Συνδεθείτε admin για routing. Definitions/connection fields είναι instance-managed, ενώ χρήστες αποθηκεύουν generation, credentials και activation.
• Με legacy endpoint ή api_url, εισάγετε πλήρες URL μαζί με operation, π.χ. https://provider.example/v1/chat/completions. API root μόνο στο base_url με api_mode και προαιρετικό api_path.
• Absolute HTTP/HTTPS γίνονται δεκτά. HTTP μόνο self-hosted trusted network, επειδή keys, prompt και responses δεν έχουν transport encryption.
• Κενό override χρησιμοποιεί bundled endpoint. Explicit malformed/unsafe απορρίπτεται, χωρίς silent fallback.
• Environment key χρησιμοποιείται μόνο όταν unshadowed bundled definition διατηρεί trusted root, auth fields, capability endpoints/selectors και routing defaults. Imports, writable definitions με bundled ID και admin custom routes χρειάζονται credential ίδιου account. Μόνο environment key σημαίνει unavailable και skip discovery.
• Pre-upgrade custom definitions μπαίνουν quarantine επειδή δεν είχε καταγραφεί admin provenance. Κάντε re-import ως admin και re-activate ανά χρήστη. Direct edit ξαναβάζει quarantine· χρησιμοποιήστε install/update flow για source path/hash.
• Credentials δένονται με route, auth contract, definition και source. Με αλλαγή σώστε ξανά. Old unbound μεταφέρεται μόνο σε exact anchored bundled route.
• Imported plugin μπορεί api_url ως legacy alias· endpoint υπερισχύει. Άλλο model list στο πλήρες models_endpoint, validated χωρίς redirects.
• Ενεργοποιήστε μετά save endpoint/credential. Activation παράγει /models και χρησιμοποιεί credential activating user, εκτός models_endpoint. Save/reset fields κάνει refresh και περιμένει πριν UI reload. Activation είναι per-account.
• Στο Settings → Plugins, επιλέξτε Refresh models. Table read-only για current account. Transient failure κρατά previous catalog ή fallback model_map, άρα completed check δεν αποδεικνύει υγεία endpoint.
• Automatic discovery απαιτεί OpenAI-compatible data. Catalogs αποθηκεύονται ανά χρήστη χωρίς αλλαγή JSON. Normal activation κρατά προηγούμενο αν unavailable, ενώ connection change καθαρίζει πρώτα και failure χρησιμοποιεί model_map.
• Image models, overrides και keys επιλύονται για current user· ελέγξτε auth αν φαίνεται άλλος.
• Αν upgraded non-admin είχε routing value, Reset το αφαιρεί ώστε role change να μην το αναβιώσει και καθαρίζει stale discovered models.
• Requests προέρχονται backend· localhost σε container σημαίνει container.
• Provider requests δεν ακολουθούν redirects. Ορίστε final validated URL.

Το Chat χρησιμοποιεί λάθος ή μη διαθέσιμο πάροχο

Το ίδιο model ID μπορεί να υπάρχει σε Ollama και πολλά plugins. Chat sessions και default preferences αποθηκεύουν provider και raw ID, άρα ίδια ονόματα είναι ανεξάρτητα.

• Σε unavailable, re-activate/reinstall exact plugin και ελέγξτε model map.
• Αν αφαιρέθηκε σκόπιμα, επιλέξτε replacement. Δεν ανακατευθύνεται σε ίδιο όνομα άλλου παρόχου.
• Older sessions χωρίς provider metadata κρατούν legacy name-only routing και φαίνονται "provider not recorded". Επιλέξτε ξανά Ollama/plugin για pin.
• Persona παραμένει persona:<id>. Νέες επιλογές γράφουν Ollama backing· ιστορικές χωρίς metadata μένουν compatible.

Προβλήματα Work

Το Work λείπει ή αναφέρει Runtime unavailable

Απαιτεί current authenticated account με Work access — admin ή active user αφού admin το ανοίξει από την καρτέλα User Management στις Settings. Το container runtime πρέπει να είναι διαθέσιμο στο backend:

docker info
docker version

Στο default Docker επιβεβαιώστε ότι τρέχει και ο OS user μπορεί WORK_DOCKER_COMMAND. Το npx δεν εγκαθιστά Docker. Χωρίς runtime, η υπόλοιπη app μένει διαθέσιμη και δεν εκτελούνται model commands στον host.

Τα Compose files mountάρουν host socket. Σε Kubernetes ενεργοποιήστε Pod/PVC με work.enabled=true, ποτέ node runtime socket. Αν ακόμη Runtime unavailable, η σελίδα δείχνει ποιο ισχύει:

Μήνυμα	Αιτία και λύση
The "docker" CLI is not installed…	Custom image χωρίς docker-cli. Χρησιμοποιήστε official ή ορίστε WORK_DOCKER_COMMAND.
No Docker daemon is reachable…	Socket mount αφαιρέθηκε ή daemon stopped. Επαναφέρετε και ξεκινήστε Docker.
The Docker socket is mounted but…cannot open	Διαφορετική ομάδα socket. Ορίστε DOCKER_GID στο .env και recreate.
Η οθόνη ή ο ήχος Work κλείνει με WebSocket 1006 και log screen is unreachable	Το backend σε container καλεί το δικό του loopback. Σε Docker Desktop χρησιμοποιήστε το προεπιλεγμένο WORK_DOCKER_PUBLISHED_HOST=host.docker.internal· σε native Docker Engine ορίστε επιπλέον το WORK_PREVIEW_BIND στο μη δημόσιο gateway της γέφυρας Docker και κάντε recreate το Libre WebUI.

Διαβάστε την ομάδα μέσω container, επειδή macOS host αναφέρει άλλη τιμή:

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

Αυτό το socket δίνει έλεγχο ισοδύναμο με root στον Docker host. Διαβάστε Work: απομονωμένοι χώροι για τις συνέπειες στην εγκατάσταση.

Το μοντέλο δεν υποστηρίζει εργαλεία

Το Work χρειάζεται tool-capable chat. Σε Ollama επιλέξτε installed model με tools. Για plugin:

• Επιβεβαιώστε active plugin, model στη λίστα, API key admin και tool calls για ακριβές model.

Το Libre δεν δρομολογεί σιωπηρά failed Work σε άλλο πάροχο.

Αίτημα Work επιστρέφει HTTP 429

Έφτασε limit task ή active runtime. Default δύο container tasks στην instance και ένα ανά user· preview επίσης καταλαμβάνει capacity. Περιμένετε, σταματήστε preview ή ελέγξτε WORK_MAX_ACTIVE_RUNTIMES_* και WORK_MAX_TASKS_*.

Αποτυγχάνει package ή network access

Νέα tasks χρησιμοποιούν Docker bridge για packages/preview. Ελέγξτε DNS, proxy, registry και Activity. Δεν mountάρονται host SSH keys, cloud credentials, browser profiles ή socket.

Το Work preview δεν ξεκινά

• Server bind 0.0.0.0 στο WORK_PREVIEW_PORT (default 4173).
• Κενό command ανιχνεύει package.json dev ή index.html, και μία nested app.
• Με πολλαπλές/no entry, εισάγετε explicit command. Ξεκινά /workspace, άρα cd <app-directory> && ... για nested.
• Αναπτύξτε error details και σταματήστε υπάρχον preview πριν άλλο command.

Preview URL έχει dynamic loopback port, άρα browser και backend ίδιο μηχάνημα. Remote browser δεν φτάνει loopback και HTTPS μπορεί να μπλοκάρει HTTP ως mixed content.

Αρχείο workspace δεν ανοίγει ή αποθηκεύεται

File API δέχεται UTF-8 έως 2 MB. Αν άλλαξε μετά το άνοιγμα, reload πριν save. Formatting μόνο supported types κάτω 100.000 chars/4.000 lines και highlight παύει σε μεγάλα.

Unsaved edits είναι browser draft, όχι υποκατάστατο persistent save.

Εργασία ή preview σταμάτησε

Stop run/preview ή restart σταματά disposable processes αλλά κρατά named volume. Ξανανοίξτε task/preview. Delete μετά επιβεβαίωση αφαιρεί μόνιμα task και workspace.

Προβλήματα σύνδεσης και εγγραφής

Ο πρώτος χρήστης δεν είναι admin

Μόνο το πρώτο account σε νέα βάση γίνεται admin. Υπάρχουσες βάσεις κρατούν users/roles.

Σφάλματα JWT

Ορίστε σταθερό secret σε παραγωγή:

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

Αλλαγή JWT_SECRET ακυρώνει συνεδρίες.

Το Turnstile μπλοκάρει εγγραφή

Ενεργοποιείται μόνο με δύο keys:

TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...

Επιβεβαιώστε site key/domain και valid secret.

Αποτυχία OAuth redirects

Ορίστε callback URLs στο dashboard παρόχου και backend .env:

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

Δέχεται PDF, Office, Markdown, HTML, code, CSV έως 10 MB.

Αν search λειτουργεί αλλά semantic retrieval όχι:

1. Εγκαταστήστε embedding όπως nomic-embed-text.
2. Ενεργοποιήστε embeddings.
3. Αναγεννήστε από document settings ή API.

ollama pull nomic-embed-text

Keyword search λειτουργεί και χωρίς embeddings.

Προβλήματα preview artifact

Για παιχνίδια/interactive HTML ζητήστε ένα self-contained HTML με inline CSS/JS.

Αν χρειάζεται keyboard:

• Click στο preview, ή Open σε δική του καρτέλα. Μην βασίζεστε σε local files εκτός απάντησης.

Το Libre ενώνει index.html + CSS + JavaScript, αλλά self-contained είναι πιο αξιόπιστο.

Προβλήματα Docker

Το container δεν φτάνει Ollama

Χρησιμοποιήστε external Ollama compose όταν δεν είναι στην ίδια stack:

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

Τα δεδομένα δεν παραμένουν

Mount persistent volume και ορίστε DATA_DIR. Το encryption key αποθηκεύεται μόνιμα με DATA_DIR/Docker.

Επαναφορά τοπικών δεδομένων

Σταματήστε, αντιγράψτε και αφαιρέστε data directory. Default development backend/data.

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

Κάντε restart backend και νέο account.

Παραμένει το πρόβλημα

Ανοίξτε issue με:

• έκδοση/commit Libre WebUI, τρόπο εγκατάστασης, OS, Node.js/Ollama/Docker·
• docker info για Work, backend logs, console errors, exact model/provider και Work Activity output.