Усунення неполадок

Починайте з рівня, що відмовляє: браузер, фронтенд, сервер, 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 і залежності

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 від каталогу сервера, не поточного каталогу оболонки: DATA_DIR=./data означає backend/data, а історичне DATA_DIR=./backend/data — backend/backend/data. Переконайтеся в праві запису. Без змінної Libre зберігає історичний каталог, якщо він єдиний. Якщо дані є в обох місцях, зупиніть Libre, скопіюйте обидва й свідомо виберіть або мігруйте; Libre ніколи не об’єднує різні бази.

Кінцеві точки розрізняють живий процес і готовий застосунок:

• /health і /health/live повертають 200, коли сервер відповідає HTTP. Необов’язкові провайдери не впливають.
• /health/ready повертає 503, коли потрібна база, схема, сховище або зареєстрована залежність недоступні. Не чекає необов’язкових провайдерів і не розкриває внутрішніх помилок.
• /health/deep у обмеженому worker перевіряє цілісність SQLite й зовнішні ключі та додає необов’язкові серверні перевірки Ollama. Збій провайдера є попередженням, а не неготовністю. Потрібен чинний bearer-токен адміністратора; точка не призначена для частого оркестратора.

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

Браузер не досягає сервера

Під час розробки фронтенд використовує VITE_API_BASE_URL, якщо задано, інакше типовий сервер.

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

VITE_WS_BASE_URL необов’язкова, але є спільною основою socket Chat і термінала Work. Використовуйте абсолютний ws: або wss: URL; підтримується префікс шляху на кшталт wss://example.com/libre. Не додавайте облікові дані, query або fragment. Після зміни змінної Vite перезапустіть або перебудуйте фронтенд.

На сервері:

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

Для телефона, LAN або Tailscale не використовуйте localhost у браузері телефона; вкажіть IP ноутбука й запустіть:

npm run dev:host

Ця команда обслуговує фронтенд на порту 8080 і проксіює трафік API та WebSocket до локального бекенда на порту 3001. З іншого пристрою потрібен доступ лише до порту 8080. Якщо VITE_API_BASE_URL або VITE_WS_BASE_URL задано у frontend/.env, переконайтеся, що ці URL-адреси доступні з іншого пристрою, або приберіть їх, щоб використовувати проксі сервера розробки.

Chat не передає потік за зворотним проксі

Типова ознака: повідомлення надсилається, але відповіді немає, а консоль показує помилку WebSocket. Дозвольте upgrade й довгі з’єднання.

Коли задано CORS_ORIGIN або BASE_URL, заголовок Origin браузера перевіряється. Для віддаленого розгортання задайте хоча б одне; без обох фільтр лишається поблажливим для локальної розробки. Electron та інші клієнти можуть не мати Origin, але все одно обмінюють Authorization на короткий одноразовий квиток. Тримайте сервер за TLS і тими самими мережевими контролями, що HTTP API.

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

Приклади nginx і Caddy припускають проксі на Docker-хості, де Compose публікує Libre WebUI на 8080. У мережі Compose використовуйте libre-webui:3001.

nginx

nginx потребує явних заголовків upgrade; довгий тайм-аут зберігає бездіяльне з’єднання під час роботи моделі.

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 і перезавантажте nginx.

Caddy

reverse_proxy Caddy підтримує WebSocket без додаткових заголовків:

chat.example.com {
    reverse_proxy 127.0.0.1:8080
}

Traefik

Traefik також підтримує upgrade типово. У спільній мережі потрібні звичайні мітки:

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'

Якщо потік з’єднується, але згодом обривається, перевірте тайм-аут бездіяльності всіх проксі й балансувальників. У Traefik налаштуйте transport.respondingTimeouts точки входу.

Ollama не виявлено

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

Власний URL у серверному .env:

OLLAMA_BASE_URL=http://localhost:11434

Якщо Libre у Docker, а Ollama на хості, використовуйте зовнішній Compose або спрямуйте OLLAMA_BASE_URL на адресу хоста, досяжну з контейнера.

Проблеми завантаження моделей

ollama pull gemma4:12b

Якщо термінал не завантажує, проблема поза Libre WebUI.

Для Ollama Cloud використовуйте хмарний фільтр Менеджера моделей. Libre нормалізує потрібні суфікси, тож не треба вручну додавати :cloud.

Адміністратор може заборонити завантаження звичайним користувачам. Перевірте налаштування, якщо моделі видно, але не встановлюються.

Chat повільний або завершується помилкою

• Використовуйте меншу модель.
• Перевірте завантажені через ollama ps.
• Зменште контекст і максимальні токени.
• Переконайтеся, що модель уміщується в RAM/VRAM.
• Для плагіна перевірте ключ API і квоту.

Генерування зображень OpenAI недоступне

• Активуйте вбудований OpenAI. Збережіть ключ поточного користувача або налаштуйте довірений резерв OPENAI_API_KEY.
• Увімкніть генерування й виберіть оголошену GPT Image.
• Віддавайте перевагу gpt-image-2; старі ID лишаються лише для сумісності й застаріли у провайдера.
• Лишайте image_endpoint порожнім без власної сумісної Image API. Chat /responses або /chat/completions не обробляє зображення.
• Якщо OpenAI відхиляє запит із чинним ключем і квотою, перевірте право організації на GPT Image.

Доступність визначається ключем поточного користувача або довіреним резервом. Ключ іншої особи не відкриває моделі.

Проблеми кінцевої точки провайдера

У Налаштування → Плагіни:

• Виберіть Chat Completions для /chat/completions або Responses для /responses.
• Введіть корінь API, як https://provider.example/v1, у Base URL.
• Лишіть API path порожнім для типового шляху або введіть шлях із /.
• Справді власна стара повна точка має найвищий пріоритет; очистьте її при поверненні до Base URL/API Path. Значення, рівне старому типовому маніфесту, після оновлення ігнорується. Суфікс /chat/completions або /responses також визначає формат.

Імпортований JSON підтримує протоколи OpenAI Chat Completions, Responses, Anthropic або Gemini. Власна форма даних, потоку, інструмента чи відповіді потребує адаптера; сам URL її не перекладає.

URL може бути HTTP або HTTPS. HTTP передає облікові дані без шифрування, тож використовуйте лише у довіреній мережі. Base URL не може мати query або fragment, а відносний шлях — traversal, query чи fragment, зокрема багаторазово закодовані. Надмірне кодування відхиляється.

Оновлення моделей замінює відомі суфікси, зокрема /responses, на /models. Активація, ручне оновлення, зміни підключення, збереження/видалення ключа й скидання використовують точку та ключ поточного користувача; інші параметри генерації не викликають мережу. ID зберігаються per користувача, не в спільному JSON. Якщо маршрут не підтримується, задайте model_map.

Запити провайдерів навмисно не йдуть за перенаправленнями для виявлення, Chat, Work, зображень, embedding і TTS. Налаштуйте остаточний URL, щоб Authorization не перейшов у неперевірене місце.

Якщо Work повідомляє про зміну маршруту під час запуску, почніть новий після завершення налаштування. Work зупиняється до наступного запиту, щоб попередній стан інструментів не перейшов через іншу межу режиму, точки або ключа.

Запити виходять із сервера, тому localhost у контейнері означає контейнер. У Compose/Kubernetes використовуйте DNS служби, наприклад http://ai-gateway:8080/v1. http://host.docker.internal:8080/v1 працює лише коли середовище надає цей псевдонім. HTTP лишається відкритим текстом навіть у приватній мережі.

Моделі зображень, перевизначення й ключі також визначаються для поточного користувача. Якщо використано чужі налаштування, перевірте автентифікацію запиту.

Додаткові правила:

• Маршрути змінює лише адміністратор; звичайний користувач зберігає генерацію, облікові дані та активацію.
• Старий endpoint або api_url має бути повним URL операції, наприклад https://provider.example/v1/chat/completions; корінь вводьте в base_url із api_mode та api_path.
• Приймаються абсолютні HTTP/HTTPS. HTTP лише для довіреного власного шлюзу.
• Порожнє перевизначення використовує вбудовану точку; неправильне відхиляється, не повертаючись непомітно.
• Ключ середовища використовується лише для незатіненого вбудованого визначення зі збереженим довіреним маршрутом, автентифікацією, точками й типовими змінними. Імпортовані, записувані з вбудованим ID або власні маршрути адміністратора потребують ключа того самого облікового запису; інакше провайдер недоступний і виявлення пропускається.
• Старі власні визначення перебувають у карантині; повторно імпортуйте JSON як адміністратор, потім активуйте для кожного. Пряма зміна схваленого JSON знову ізолює його; використовуйте процес установлення або оновлення, що записує шлях і хеш.
• Збережені облікові дані прив’язані до маршруту, контракту, визначення й джерела. Після зміни точки або визначення збережіть їх знову. Старі неприв’язані мігрують лише на точному вбудованому маршруті.
• api_url є старим псевдонімом повної операції; endpoint має пріоритет. Для окремого виявлення задайте повний models_endpoint; він перевіряється без перенаправлень.
• Активуйте після збереження точки й даних. Активація виводить /models і використовує дані активуючого користувача, якщо немає models_endpoint. Збереження/скидання цих полів оновлює виявлення, а запит чекає завершення. Інший користувач активує окремо.
• Оновити моделі явно перевіряє каталог. Таблиця лише для читання. Тимчасова помилка зберігає попередній каталог або model_map, тому завершена перевірка сама не доводить справність.
• Автоматичне виявлення очікує масив data з ID. Успішний каталог per користувача. Звичайна активація зберігає старий при недоступності; зміна підключення спочатку очищає його, тому невдача використовує model_map.
• Якщо неадміністратор колись зберіг маршрут, використайте Скинути. Ігнороване старе значення й каталог буде очищено до можливої зміни ролі.
• Запити виходять із сервера; localhost у контейнері — сам контейнер.
• Провайдери не переходять за перенаправленнями.

Chat використовує неправильного провайдера або показує недоступність

Однаковий ID може бути в Ollama й кількох плагінах. Поточні сеанси й типова модель зберігають провайдера разом із сирим ID, тому вибори незалежні.

• Якщо провайдер недоступний, повторно активуйте або встановіть точний плагін і перевірте ID у карті.
• Якщо його видалено навмисно, явно виберіть заміну; Libre не перенаправить точний вибір до одноіменного.
• Старі сеанси можуть не мати метаданих провайдера й використовують старий маршрут за назвою. Селектор показує «провайдера не записано». Повторно виберіть Ollama або плагін.
• Персони лишають persona:<id>. Нові записують Ollama як основу; старі без метаданих лишають сумісність.

Проблеми Work

Work відсутній або середовище недоступне

Потрібен чинний користувач із доступом та середовище, досяжне сервером:

docker info
docker version

Для Docker перевірте запуск і право користувача виконувати WORK_DOCKER_COMMAND. npx не встановлює Docker. За відсутності середовища решта Libre працює й не виконує команди на хості.

Compose підключає socket хоста. У Kubernetes ввімкніть work.enabled=true і не підключайте socket вузла. Якщо Compose все одно повідомляє недоступність:

Повідомлення	Причина та виправлення
The "docker" CLI is not installed…	Власний образ без docker-cli; використайте офіційний або задайте WORK_DOCKER_COMMAND.
No Docker daemon is reachable…	Немає socket або демон зупинено; поверніть підключення й запустіть Docker.
The Docker socket is mounted but…cannot open	Група socket відрізняється; задайте DOCKER_GID і пересоздайте контейнер.
Екран або звук Work закривається з WebSocket 1006, а в журналі — screen is unreachable	Бекенд у контейнері звертається до власного loopback. На Docker Desktop залиште вбудований WORK_DOCKER_PUBLISHED_HOST=host.docker.internal; на нативному Docker Engine додатково задайте WORK_PREVIEW_BIND на непублічний шлюз мосту Docker і пересоздайте Libre WebUI.

Читайте групу через контейнер, бо macOS показує інше значення:

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; подробиці — у Work: ізольовані робочі області.

Модель не підтримує інструменти

Для Ollama виберіть установлену модель із tools. Для плагіна перевірте активність chat/completion, модель у списку, ключ поточного адміністратора й підтримку викликів. Libre не перемикає провайдера після помилки.

Запит Work повертає HTTP 429

Досягнуто ліміт задач або активних середовищ. Типово дозволено дві задачі в інстанції й одну на користувача; активний перегляд також займає місце. Дочекайтеся, зупиніть непотрібний перегляд або перегляньте WORK_MAX_ACTIVE_RUNTIMES_* і WORK_MAX_TASKS_*.

Не працює встановлення пакетів або мережа

Нові задачі використовують міст Docker для пакетів і переглядів. Перевірте DNS, проксі, реєстр і вивід у Активності. Libre не підключає SSH-ключі хоста, хмарні дані, профілі браузера або socket Docker до задачі.

Не запускається перегляд Work

• Сервер має слухати 0.0.0.0 на WORK_PREVIEW_PORT (типово 4173).
• Порожня команда автоматично знаходить dev у package.json, index.html або один вкладений застосунок.
• Якщо знайдено кілька або жодного, введіть явну команду; вона починається в /workspace, тому для вкладеного використайте cd <app-directory> && ....
• Розгорніть помилку для виводу запуску.
• Зупиніть наявний перегляд перед іншою командою, що потребує контейнера.

URL перегляду використовує динамічний loopback. Браузер і сервер мають бути на одній машині; віддалений браузер не досягне loopback, а HTTPS може блокувати HTTP як змішаний вміст.

Файл робочої області не відкривається або не зберігається

API приймає текст UTF-8 до 2 MB. Якщо файл змінився після відкриття, перезавантажте до збереження. Форматування обмежено підтримуваними типами до 100,000 символів і 4,000 рядків; підсвічування великих файлів призупиняється. Незбережені зміни є лише чернеткою браузера, не заміною збереження.

Завдання або перегляд зупинено

Зупинка запуску, перегляду чи перезапуск Libre припиняє одноразові процеси, але зберігає іменований том. Відкрийте задачу й запустіть перегляд знову. Видалення задачі після підтвердження назавжди видаляє й робочу область.

Проблеми входу та реєстрації

Перший користувач не адміністратор

Адміністратором стає лише перший обліковий запис у новій базі. Наявна база зберігає ролі.

Помилки JWT

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

Зміна JWT_SECRET скасовує сеанси.

Turnstile блокує реєстрацію

TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...

Turnstile вмикається лише з обома ключами. Перевірте домен site key і чинність secret key.

Не працюють перенаправлення OAuth

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

Задайте однакові URL у панелі провайдера й .env сервера.

Проблеми чату з документами

Підтримуються PDF, DOCX/PPTX/XLSX, Markdown, HTML, код і CSV до 10 MB. Якщо пошук за словами працює, а семантичний ні:

1. Установіть nomic-embed-text.
2. Увімкніть векторні подання.
3. Створіть їх повторно в налаштуваннях або API.

ollama pull nomic-embed-text

Пошук за словами працює без подань.

Проблеми перегляду артефактів

Для гри або HTML попросіть один самодостатній файл із вбудованими CSS і JavaScript. Якщо потрібна клавіатура, клацніть усередині, відкрийте в окремій вкладці й не покладайтеся на локальні файли поза відповіддю. Libre може об’єднати index.html + CSS + JavaScript, але один файл надійніший.

Проблеми Docker

Контейнер не досягає Ollama

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

Використовуйте зовнішній Compose, якщо Ollama не в тому самому стеку.

Дані не зберігаються

Підключіть постійний том і за потреби DATA_DIR. Ключ зберігається в постійному сховищі при DATA_DIR або Docker.

Скидання локальних даних

Спершу зупиніть застосунок. Скопіюйте й видаліть фактичний каталог; типово це backend/data.

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

Запустіть сервер і створіть новий обліковий запис.

Якщо проблему не вирішено

У задачі вкажіть:

• Версію й commit Libre WebUI
• Спосіб установлення
• ОС
• Версію Node.js
• Версію Ollama
• Версію Docker і docker info для Work
• Журнали сервера біля помилки
• Помилки консолі браузера
• Точну модель або провайдера
• Вивід Активності Work при помилці задачі чи перегляду