समस्या निवारण

पहले असफल परत पहचानें: ब्राउज़र, फ़्रंटएंड, बैकएंड, Ollama, प्रदाता प्लगइन या डिप्लॉयमेंट नेटवर्क।

त्वरित जाँच

# 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

विकास में फ़्रंटएंड http://localhost:5173, बैकएंड http://localhost:3001, और npx libre-webui http://localhost:8080 उपयोग करता है।

Libre WebUI शुरू नहीं होता

node --version
npm install
npm run dev

Node.js 22.22 या नया चाहिए।

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

पुरानी प्रक्रिया रोकें या पोर्ट बदलें।

डेटा DATA_DIR या backend/data में है। स्रोत लॉन्च सापेक्ष DATA_DIR को बैकएंड से resolve करता: DATA_DIR=./data → backend/data, पुराना DATA_DIR=./backend/data → backend/backend/data। लेखन अनुमति दें। दोनों जगह स्थिति हो तो Libre रोकें, दोनों backup और जानबूझकर चुनें/migrate करें; मिलाता नहीं होता।

• /health, /health/live: प्रक्रिया HTTP दे तो 200; वैकल्पिक प्रदाता अप्रभावित।
• /health/ready: आवश्यक database/schema/storage/platform dependency न हो तो 503, आंतरिक details छिपी।
• /health/deep: bounded worker में SQLite integrity/foreign keys और वैकल्पिक Ollama probes; प्रदाता outage warning। वर्तमान व्यवस्थापक bearer टोकन चाहिए, frequent orchestrator probe नहीं।

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

ब्राउज़र बैकएंड तक नहीं पहुँचता

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

फ़्रंटएंड सेट होने पर VITE_API_BASE_URL उपयोग करता है। VITE_WS_BASE_URL Chat/Work sockets का साझा वैकल्पिक base है। पूर्ण ws:/wss: URL और wss://example.com/libre जैसा पथ prefix supported; क्रेडेंशियल/क्वेरी/fragment नहीं। Vite बदलाव के बाद rebuild/restart।

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

Phone/LAN/Tailscale में phone पर localhost नहीं, laptop IP और:

npm run dev:host

यह frontend को port 8080 पर serve करता है और API व WebSocket ट्रैफ़िक को local backend port 3001 पर proxy करता है। दूसरी डिवाइस से केवल port 8080 पहुँच योग्य होना चाहिए। यदि frontend/.env में VITE_API_BASE_URL या VITE_WS_BASE_URL सेट है, तो सुनिश्चित करें कि वे URL दूसरी डिवाइस से पहुँच योग्य हों, या dev-server proxy उपयोग हेतु उन्हें हटा दें।

Reverse Proxy के पीछे Chat स्ट्रीम नहीं करता

संदेश जाता पर reply नहीं और WebSocket विफलता हो तो upgrade और दीर्घकालिक connections अनुमति करें।

CORS_ORIGIN या BASE_URL सेट होने पर ब्राउज़र Origin जाँचता है। दूरस्थ डिप्लॉयमेंट में एक सेट करें; दोनों न हों तो स्थानीय dev permissive। Electron बिना Origin हो सकता पर Authorization को short एकबारगी ticket में बदलता है। बैकएंड को TLS और HTTP API जैसे controls पीछे रखें।

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

Proxy Docker host पर हो तो port 8080; Compose नेटवर्क में 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;
}

nginx -t के बाद reload।

Caddy

Caddy का reverse_proxy WebSocket को स्वतः संभालता है:

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'

बाद में drop हो तो proxy/load balancer idle समय-सीमा और Traefik transport.respondingTimeouts जाँचें।

Ollama नहीं मिलता

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

OLLAMA_BASE_URL=http://localhost:11434

Libre Docker में और Ollama host पर हो तो बाहरी Compose या container-reachable OLLAMA_BASE_URL।

मॉडल डाउनलोड समस्याएँ

ollama pull gemma4:12b

Terminal fail हो तो Libre बाहर समस्या। Ollama Cloud के लिए cloud filter; Libre suffix normalize करता, :cloud हाथ से नहीं। व्यवस्थापक सामान्य उपयोगकर्ता के pulls disable कर सकता है।

Chat धीमा या विफल

• छोटा मॉडल
• ollama ps
• context/max tokens घटाएँ
• RAM/VRAM में fit
• प्लगइन API कुंजी/quota

OpenAI इमेज जनरेशन अनुपलब्ध

• OpenAI प्लगइन सक्रिय; वर्तमान उपयोगकर्ता कुंजी या विश्वसनीय OPENAI_API_KEY वैकल्पिक।
• इमेज जनरेशन enable और GPT इमेज मॉडल।
• gpt-image-2 पसंद; पुराने deprecated compatibility।
• Compatible own इमेज API न हो तो image_endpoint blank। Chat /responses//chat/completions इमेज नहीं।
• मान्य कुंजी/quota पर reject तो organization eligibility।

दूसरे उपयोगकर्ता का कुंजी इमेज मॉडल नहीं खोलता।

प्रदाता एंडपॉइंट समस्याएँ

• /chat/completions के लिए Chat Completions, /responses के लिए उत्तर।
• API root https://provider.example/v1 मूल URL में।
• डिफ़ॉल्ट पथ के लिए API पथ blank, कस्टम leading slash।
• पुराना पूर्ण एंडपॉइंट highest precedence; मूल URL/API पथ लौटते साफ़। /chat/completions//responses suffix अनुरोध प्रारूप भी तय।

JSON केवल OpenAI Chat Completions, उत्तर, Anthropic या Gemini wire प्रारूप; proprietary payload/stream/tool shape बैकएंड adapter चाहता है।

HTTP क्रेडेंशियल खुला पाठ भेजता; विश्वसनीय नेटवर्क में। मूल URL क्वेरी/fragment नहीं; सापेक्ष पथ traversal/क्वेरी/fragment नहीं। Excess encoding reject।

मॉडल रीफ़्रेश known suffix को /models करता। Activation, रीफ़्रेश, कनेक्शन, कुंजी और रीसेट वर्तमान उपयोगकर्ता एंडपॉइंट/कुंजी; IDs प्रति उपयोगकर्ता, unsupported रूट पर model_map।

प्रदाता अनुरोध खोज, Chat, Work, इमेज, embeddings, TTS सहित redirects नहीं follow करते। अंतिम URL सीधे सेट करें।

Work रूटिंग changed कहे तो सेटिंग के बाद नया run; prior tool स्थिति दूसरी मोड/एंडपॉइंट/API कुंजी boundary में नहीं जाता।

अनुरोध बैकएंड से; container localhost container। Compose/Kubernetes सेवा DNS http://ai-gateway:8080/v1; http://host.docker.internal:8080/v1 केवल alias समर्थन पर। HTTP खुला पाठ।

• रूटिंग केवल व्यवस्थापक; उपयोगकर्ता जनरेशन, क्रेडेंशियल, activation।
• endpoint/api_url पूर्ण ऑपरेशन URL है, जैसे https://provider.example/v1/chat/completions; मूल URL को base_url में api_mode और api_path के साथ दें।
• पूर्ण HTTP/HTTPS; HTTP विश्वसनीय केवल।
• Blank bundled एंडपॉइंट; malformed reject।
• पर्यावरण कुंजी केवल unshadowed विश्वसनीय bundled रूट; imported/writable/कस्टम उसी खाते का क्रेडेंशियल।
• Pre-upgrade कस्टम definitions quarantined; व्यवस्थापक re-import, उपयोगकर्ता reactivate; सीधा edit re-quarantine।
• सहेजा क्रेडेंशियल रूट/auth/परिभाषा/स्रोत bound; बदलाव पर resave।
• api_url पुराना alias; endpoint wins; खोज अलग हो तो models_endpoint।
• Activation सहेजा एंडपॉइंट से /models derive और activating उपयोगकर्ता क्रेडेंशियल; कनेक्शन save/रीसेट खोज रीफ़्रेश।
• रीफ़्रेश मॉडल स्पष्ट; तालिका केवल-पढ़ने; transient विफलता previous कैटलॉग या model_map।
• खोज OpenAI data array; प्रति उपयोगकर्ता। कनेक्शन बदलाव stale कैटलॉग साफ़।
• पुराना non-व्यवस्थापक रूटिंग के लिए रीसेट।
• बैकएंड अनुरोध redirects नहीं।

Chat गलत प्रदाता या अनुपलब्ध दिखाता है

समान मॉडल ID Ollama और प्लगइन में हो सकता; वर्तमान sessions प्रदाता + कच्चा ID save।

• सटीक प्लगइन reactivate/reinstall और मॉडल मानचित्र।
• हटाया हो तो replacement स्पष्ट रूप से select; समान-name redirect नहीं।
• पुराना sessions प्रदाता metadata बिना name-केवल रूटिंग और “प्रदाता not recorded”; reselect।
• Persona persona:<id>, नया selection Ollama backing।

Work समस्याएँ

Work नहीं या रनटाइम अनुपलब्ध

वर्तमान access खाता और बैकएंड-reachable रनटाइम:

docker info
docker version

Docker running और उपयोगकर्ता WORK_DOCKER_COMMAND चला सके। npx Docker स्थापित नहीं। रनटाइम अनुपस्थित पर rest app works, host commands नहीं।

Compose host socket mount; Kubernetes work.enabled=true, node socket नहीं। संदेश:

संदेश	समाधान
The "docker" CLI is not installed…	कस्टम इमेज में docker-cli नहीं; official या WORK_DOCKER_COMMAND.
No Docker daemon is reachable…	Socket/daemon नहीं; restore/शुरू।
The Docker socket is mounted but…cannot open	समूह अलग; .env में DOCKER_GID, recreate।
Work screen/audio WebSocket 1006 से बंद और log में screen is unreachable	कंटेनर वाला backend अपने ही loopback पर dial कर रहा है। Docker Desktop पर दिया गया WORK_DOCKER_PUBLISHED_HOST=host.docker.internal रखें; native Docker Engine पर WORK_PREVIEW_BIND को non-public Docker bridge gateway पर भी सेट करें, फिर Libre WebUI recreate करें।

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-equivalent control; Work देखें।

मॉडल में टूल समर्थन नहीं

Ollama tools; प्लगइन सक्रिय chat/completion, मॉडल सूची, व्यवस्थापक API कुंजी और टूल कॉल। नहीं वैकल्पिक।

HTTP 429

Task/रनटाइम admission सीमा। डिफ़ॉल्ट instance two, प्रति उपयोगकर्ता one; preview capacity रखता। Wait/रोकें या WORK_MAX_ACTIVE_RUNTIMES_*, WORK_MAX_TASKS_*।

Package या नेटवर्क विफल

Docker DNS, proxy, registry और Activity आउटपुट। Libre host SSH/cloud/ब्राउज़र प्रोफ़ाइल/Docker socket task में नहीं mount करता।

Preview शुरू नहीं

• 0.0.0.0 पर WORK_PREVIEW_PORT (4173)।
• Blank command package.json dev, index.html या एकल nested app।
• कई/कोई नहीं पर स्पष्ट command; /workspace से, cd <app-directory> && ...।
• त्रुटि विवरण खोलें।
• मौजूदा preview रोकें।

Preview dynamic loopback; ब्राउज़र/बैकएंड समान machine। दूरस्थ ब्राउज़र नहीं पहुँचता, HTTPS HTTP को mixed सामग्री block कर सकता।

फ़ाइल नहीं खुलती/सहेजती

UTF-8 2 MB तक। बाद में बदली हो तो reload। Formatting 100,000 chars/4,000 lines supported प्रकार; highlighting large फ़ाइलें pause। Draft saving का substitute नहीं।

Task/Preview रुका

रोकें/restart disposable processes रोकता पर named volume बचाता। Reopen/restart। हटाएँ task permanent workspace removal।

Login/Signup समस्याएँ

पहला व्यवस्थापक केवल fresh DB का पहला खाता। मौजूदा roles stay।

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

स्थिर JWT_SECRET सेट करें; JWT_SECRET बदलने से sessions अमान्य होते हैं।

TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...

दोनों keys पर सक्षम; domain/रहस्य जाँचें।

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

प्रदाता dashboard और बैकएंड .env में सटीक URLs।

दस्तावेज़ Chat समस्याएँ

PDF, DOCX/PPTX/XLSX, Markdown, HTML, code, CSV 10 MB। Semantic नहीं तो nomic-embed-text स्थापित, embeddings enable/regenerate:

ollama pull nomic-embed-text

कीवर्ड खोज embeddings बिना चलता।

Artifact Preview समस्याएँ

Inline CSS/JavaScript वाला एकल self-contained HTML माँगें। Keyboard के लिए click preview, own tab, उत्तर में न आए स्थानीय फ़ाइलें पर नहीं। Libre index.html + CSS + JavaScript bundle कर सकता, एकल फ़ाइल reliable।

Docker समस्याएँ

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

Ollama समान stack में न हो तो बाहरी Compose। डेटा persist न हो तो स्थायी volume और DATA_DIR।

स्थानीय डेटा रीसेट

App रोकें, actual डायरेक्टरी backup/remove, डिफ़ॉल्ट backend/data:

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

बैकएंड शुरू और नया खाता।

फिर भी समस्या

इश्यू में Libre version/commit, स्थापित विधि, OS, Node.js/Ollama/Docker versions, Work के लिए docker info, बैकएंड लॉग, ब्राउज़र console, सटीक मॉडल/प्रदाता और Work Activity आउटपुट दें।