Pemecahan Masalah

Mulailah dari lapisan yang gagal: peramban, frontend, backend, Ollama, plugin penyedia, atau jaringan deployment.

Pemeriksaan Cepat

# 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

Dalam pengembangan, frontend biasanya berjalan di http://localhost:5173 dan backend di http://localhost:3001. Alur npx libre-webui terpaket menyajikan aplikasi di http://localhost:8080.

Libre WebUI Tidak Dapat Dimulai

Periksa Node dan dependensi

node --version
npm install
npm run dev

Node.js 22.22 atau yang lebih baru diperlukan.

Port sudah digunakan

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

Hentikan proses lama atau konfigurasikan port lain.

Backend tidak dapat menulis data

Backend menyimpan data di bawah DATA_DIR jika ditetapkan, atau di backend/data jika tidak. Peluncuran dari sumber menyelesaikan DATA_DIR relatif dari direktori backend, bukan direktori kerja shell saat ini. Karena itu, DATA_DIR=./data memilih backend/data, sedangkan DATA_DIR=./backend/data yang didukung secara historis memilih backend/backend/data. Pastikan direktori terpilih dapat ditulis. Jika DATA_DIR tidak ditetapkan, Libre mempertahankan direktori historis ketika itu satu-satunya penyimpanan yang ada. Jika kedua lokasi berisi data, hentikan Libre, cadangkan keduanya, lalu pilih atau migrasikan secara sengaja; Libre tidak pernah menggabungkan atau menyalin database yang berbeda.

Endpoint kesehatan sengaja membedakan proses yang berjalan dari aplikasi yang dapat digunakan:

• /health dan /health/live mengembalikan 200 selama proses backend dapat melayani HTTP. Penyedia model opsional tidak memengaruhi status hidup.
• /health/ready mengembalikan 503 ketika database, skema, penyimpanan, atau dependensi platform terdaftar yang wajib tidak tersedia. Endpoint ini tidak menunggu penyedia model opsional. Respons publiknya tidak menyertakan pesan kesalahan atau detail internal.
• /health/deep melakukan pemeriksaan integritas dan kunci asing SQLite dalam worker terbatas serta menggabungkan pemeriksaan penyedia tingkat server opsional seperti Ollama. Gangguan penyedia opsional muncul sebagai peringatan dan tidak membuat dependensi wajib tidak siap. Endpoint memerlukan token bearer administrator saat ini dan tidak cocok untuk pemeriksaan orchestrator yang sering.

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

Peramban Tidak Dapat Menjangkau Backend

Untuk pengembangan lokal, frontend menggunakan VITE_API_BASE_URL jika ditetapkan dan jika tidak, kembali ke backend pengembangan.

Contoh .env frontend:

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

VITE_WS_BASE_URL bersifat opsional, tetapi jika ditetapkan menjadi dasar bersama untuk soket Chat dan terminal Work. Gunakan URL ws: atau wss: absolut; prefiks jalur seperti wss://example.com/libre didukung. Jangan sertakan kredensial, parameter kueri, atau fragmen. Mulai ulang/bangun ulang frontend setelah mengubah variabel Vite.

Contoh .env backend:

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

Untuk akses ponsel, LAN, atau Tailscale, jangan arahkan peramban ponsel ke localhost; gunakan IP LAN atau Tailscale laptop dan jalankan server pengembangan dengan pengikatan host:

npm run dev:host

Ini menyajikan frontend pada port 8080 dan mem-proksi trafik API dan WebSocket ke backend lokal pada port 3001. Hanya port 8080 yang perlu dapat dijangkau dari perangkat lain. Jika VITE_API_BASE_URL atau VITE_WS_BASE_URL disetel di frontend/.env, pastikan URL tersebut dapat dijangkau dari perangkat lain atau hapus agar menggunakan proksi server pengembangan.

Chat Tidak Mengalir di Balik Reverse Proxy

Gejala umumnya adalah pesan terkirim tetapi balasan tidak pernah tampil, sementara konsol peramban menunjukkan kegagalan koneksi WebSocket. Pastikan proksi mengizinkan peningkatan WebSocket dan tidak menutup koneksi berumur panjang.

Jika salah satu nilai dikonfigurasi, peningkatan peramban yang mengirim header Origin diperiksa terhadap CORS_ORIGIN dan BASE_URL. Tetapkan sedikitnya satu untuk deployment jarak jauh; jika keduanya tidak dikonfigurasi, filter Origin tetap permisif demi kompatibilitas pengembangan lokal. Electron dan klien nonperamban lain boleh tidak menyertakan Origin, tetapi tetap harus terlebih dahulu menukar header Authorization dengan tiket sekali pakai berumur singkat. Pertahankan backend di balik TLS dan kontrol akses jaringan atau reverse proxy yang sama dengan API HTTP.

Untuk nama host publik, izinkan origin peramban tersebut dalam layanan Libre WebUI:

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

Contoh nginx dan Caddy berikut mengasumsikan proksi berjalan pada host Docker, tempat pengaturan Compose repositori menerbitkan Libre WebUI pada port 8080. Jika proksi bergabung dengan jaringan Compose, gunakan libre-webui:3001 sebagai alamat upstream.

nginx

nginx mengharuskan header peningkatan diteruskan secara eksplisit. Batas waktu baca yang lebih panjang mempertahankan koneksi chat yang sedang menganggur tetap terbuka saat model bekerja.

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

Muat ulang nginx setelah memvalidasi konfigurasi dengan nginx -t.

Caddy

reverse_proxy Caddy mendukung WebSocket secara langsung, sehingga header peningkatan tidak diperlukan:

chat.example.com {
    reverse_proxy 127.0.0.1:8080
}

Traefik

Traefik juga menangani peningkatan WebSocket secara bawaan. Jika penyedia Docker miliknya berbagi jaringan Libre WebUI, hanya label router dan layanan biasa yang diperlukan, misalnya:

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'

Jika aliran tersambung tetapi kemudian terputus, periksa batas waktu diam pada proksi atau load balancer di depan Traefik. Jika Traefik sendiri menegakkan batas tersebut, sesuaikan pengaturan transport.respondingTimeouts pada titik masuk.

Ollama Tidak Terdeteksi

Pastikan Ollama berjalan

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

Konfigurasikan URL Ollama khusus

.env backend:

OLLAMA_BASE_URL=http://localhost:11434

Jika Libre WebUI berjalan di Docker dan Ollama berjalan pada host, gunakan berkas Compose Ollama eksternal atau arahkan OLLAMA_BASE_URL ke alamat host yang dapat dijangkau dari kontainer.

Masalah Pengunduhan Model

Unduh dari terminal terlebih dahulu

ollama pull gemma4:12b

Jika pengunduhan dari terminal gagal, masalah berada di luar Libre WebUI.

Model cloud

Gunakan filter cloud di Pengelola Model untuk model Ollama Cloud. Libre WebUI menormalkan sufiks cloud yang diperlukan melalui alur tersebut, sehingga pengguna tidak perlu menambahkan :cloud secara manual untuk entri cloud yang didukung.

Pengguna tidak dapat mengunduh model

Administrator dapat menonaktifkan pengunduhan model bagi pengguna biasa. Periksa pengaturan administrator jika pengguna nonadministrator dapat menelusuri model tetapi tidak dapat menginstalnya.

Chat Lambat atau Gagal

• Gunakan model yang lebih kecil.
• Periksa model yang dimuat dengan ollama ps.
• Kurangi panjang konteks.
• Kurangi token maksimum untuk respons yang sangat panjang.
• Pastikan model muat dalam RAM/VRAM.
• Untuk plugin penyedia, pastikan kunci API dan kuota penyedia tersedia.

Pembuatan Gambar OpenAI Tidak Tersedia

• Aktifkan penyedia OpenAI yang disertakan. Simpan kunci API untuk pengguna saat ini, atau konfigurasikan fallback lingkungan OPENAI_API_KEY milik penyedia terpaket tepercaya.
• Buka pengaturan Pembuatan Gambar, aktifkan pembuatan gambar, lalu pilih salah satu model GPT Image yang ditawarkan.
• Utamakan gpt-image-2. ID GPT Image lama hanya tetap tersedia demi kompatibilitas dengan konfigurasi yang sudah ada dan telah dihentikan di upstream.
• Biarkan override image_endpoint OpenAI kosong kecuali Anda mengoperasikan endpoint gambar yang kompatibel. Endpoint Chat /responses atau /chat/completions tidak dapat memproses permintaan API Gambar.
• Jika OpenAI menolak permintaan GPT Image meski kunci dan kuota valid, pastikan organisasi API memenuhi syarat untuk menggunakan model GPT Image.

Ketersediaan gambar dievaluasi menggunakan kredensial tersimpan milik pengguna saat ini atau fallback lingkungan penyedia terpaket tepercaya. Kunci yang hanya disimpan dalam pengaturan pengguna lain tidak menampilkan model gambar.

Masalah Endpoint Penyedia

Jika penyedia kompatibel OpenAI menerima permintaan pada jalur yang salah, periksa pengaturannya di Pengaturan → Plugin:

• Pilih Chat Completions untuk payload /chat/completions atau Responses untuk payload /responses.
• Masukkan root API, seperti https://provider.example/v1, sebagai URL dasar.
• Biarkan jalur API kosong untuk nilai bawaan mode, atau masukkan jalur berawalan garis miring yang diberikan penyedia.
• Endpoint penuh lama yang benar-benar khusus sengaja memiliki prioritas tertinggi, jadi kosongkan saat kembali ke URL Dasar dan Jalur API. Nilai tersimpan yang sekadar sama dengan nilai bawaan lama manifes terpaket otomatis diabaikan setelah peningkatan. Jika endpoint khusus berakhir dengan /chat/completions atau /responses, sufiks tersebut juga menentukan format permintaan agar override tidak menerima payload yang salah.

JSON plugin yang diimpor mendukung penyedia yang menggunakan format wire kompatibel OpenAI Chat Completions, OpenAI Responses, Anthropic, atau Gemini. Jika penyedia menggunakan format payload, peristiwa streaming, panggilan alat, atau respons proprieter, penyedia memerlukan adapter backend; hanya mengganti endpoint tidak dapat menerjemahkannya.

URL penyedia dapat menggunakan HTTP atau HTTPS. HTTP mengirim kredensial dan lalu lintas penyedia tanpa enkripsi transportasi, jadi gunakan hanya untuk gateway yang dihosting sendiri pada jaringan tepercaya dan utamakan HTTPS jika TLS tersedia. URL dasar tidak boleh memuat string kueri atau fragmen, dan jalur API relatif tidak boleh memuat segmen traversal literal atau yang dikodekan berulang, string kueri, maupun fragmen. Pengodean berlebihan ditolak jika tidak menjadi stabil dalam batas validasi.

Penyegaran model mengganti sufiks operasi yang dikenal, termasuk /responses, dengan /models. Aktivasi, penyegaran eksplisit, dan override koneksi tersimpan menggunakan endpoint serta kunci API pengguna saat ini. Menyimpan atau menghapus kunci API pengguna tersebut dan mengatur ulang override koneksi juga menyegarkan daftar; parameter pembuatan yang tidak terkait tidak melakukannya. ID yang ditemukan disimpan per pengguna dan tidak pernah menimpa JSON plugin bersama. Jika rute turunan tidak didukung penyedia, konfigurasikan ID model secara manual dalam model_map plugin.

Permintaan penyedia sengaja tidak mengikuti pengalihan HTTP, termasuk penemuan model, Chat, Work, pembuatan gambar, embedding, dan teks-ke-ucapan. Konfigurasikan URL tujuan akhir, bukan URL yang mengalihkan. Perilaku tolak-aman ini mencegah header otorisasi berpindah ke tujuan yang belum divalidasi.

Jika Work melaporkan perutean penyedia berubah selama proses, mulai proses baru setelah menyelesaikan pembaruan pengaturan penyedia. Work sengaja berhenti sebelum permintaan penyedia berikutnya agar keadaan alat sebelumnya tidak dapat diputar ulang ke mode, endpoint, atau batas autentikasi kunci API yang berbeda.

Permintaan berasal dari backend, sehingga localhost merujuk ke kontainer Libre WebUI ketika backend berjalan dalam kontainer, bukan otomatis ke mesin host. Untuk deployment Compose atau Kubernetes, gunakan nama DNS layanan gateway, misalnya http://ai-gateway:8080/v1. Gunakan http://host.docker.internal:8080/v1 hanya jika runtime kontainer mengekspos alias host tersebut. Lalu lintas HTTP berupa teks biasa sekalipun nama diresolusi secara privat.

Ketersediaan model gambar, override endpoint, dan kunci API juga diselesaikan untuk pengguna saat ini. Jika permintaan gambar tampak menggunakan pengaturan penyedia akun lain, pastikan permintaan diautentikasi sebagai pengguna yang diharapkan.

Aturan keamanan dan kepemilikan berikut juga berlaku:

• Login sebagai administrator untuk mengubah routing penyedia. Definisi plugin dan field koneksi adalah konfigurasi yang dikelola instance; pengguna biasa tetap dapat menyimpan pengaturan generasi, credentials, dan state aktivasinya.
• Saat memakai override lama endpoint atau api_url, masukkan URL endpoint API lengkap beserta path operasi (misalnya https://provider.example/v1/chat/completions). Masukkan root API hanya dalam base_url, dipasangkan dengan api_mode dan api_path opsional.
• URL endpoint HTTP dan HTTPS absolut diterima. Gunakan HTTP hanya untuk gateway host mandiri pada jaringan tepercaya karena API key, prompt, dan respons dikirim tanpa enkripsi transportasi.
• Override kosong memakai endpoint yang dibundel dalam definisi plugin. Override eksplisit yang malformed atau unsafe ditolak; Libre WebUI tidak diam-diam mengirim permintaan itu ke endpoint penyedia bawaan.
• Kunci environment deployment hanya digunakan jika definisi bawaan yang tidak di-shadow mempertahankan root endpoint tepercaya, field autentikasi, endpoint capability dan selector, serta nilai bawaan variabel routing. Definisi impor, definisi writable yang memakai ulang ID bawaan, dan rute khusus tersimpan administrator memerlukan credential yang disimpan akun yang sama. Libre WebUI sengaja melaporkan penyedia tidak tersedia dan melewati discovery jika hanya kunci environment yang tersedia.
• Definisi khusus sebelum upgrade dikarantina karena rilis lama tidak mencatat provenance administrator. Impor ulang JSON sebagai administrator, lalu minta setiap pengguna mengaktifkannya kembali. Mengedit JSON plugin approved secara langsung mengarantinakannya lagi; gunakan alur install/update administrator agar source path dan hash definisinya tercatat.
• Credentials tersimpan terikat pada rute, kontrak autentikasi, definisi, dan sumber yang berlaku ketika dimasukkan. Setelah mengubah endpoint atau definisi, simpan ulang credential akun tersebut. Credential lama yang belum terikat dimigrasikan otomatis hanya pada rute bawaan anchored yang tepat.
• Plugin impor dapat memakai api_url sebagai alias URL operasi lengkap lama. endpoint menang jika keduanya diatur. Jika discovery model berada di tempat lain, atur URL daftar model lengkap dalam models_endpoint; URL divalidasi dan redirect tidak diikuti.
• Aktifkan plugin setelah menyimpan endpoint dan credential. Aktivasi menurunkan URL /models dari endpoint lengkap tersimpan dan memakai credential pengguna yang mengaktifkan untuk discovery kecuali models_endpoint diatur. Menyimpan atau me-reset field koneksi tersebut juga me-refresh discovery. Permintaan menunggu discovery sebelum UI memuat ulang daftar plugin. Aktivasi khusus akun, sehingga pengguna lain harus mengaktifkan plugin bersama secara terpisah.
• Di Settings → Plugins, pilih penyedia lalu Refresh models untuk memeriksa katalog secara eksplisit. Tabel model read-only dan menampilkan ID terkonfigurasi/terdeteksi untuk akun saat ini. Kegagalan discovery sementara mempertahankan katalog sebelumnya, atau fallback model_map plugin jika belum ada hasil, sehingga pemeriksaan selesai saja tidak membuktikan endpoint remote sehat.
• Discovery otomatis memerlukan array data kompatibel OpenAI berisi ID model. Katalog berhasil disimpan per pengguna tanpa mengubah JSON plugin bersama. Aktivasi normal mempertahankan katalog lama pengguna ketika discovery tidak tersedia. Mengubah/me-reset field koneksi menghapus katalog obsolete dahulu, sehingga refresh gagal memakai model_map plugin; konfigurasi ID fallback dalam JSON plugin bila perlu.
• Ketersediaan model gambar, override endpoint, dan API key juga diselesaikan untuk pengguna saat ini. Jika permintaan gambar tampak memakai pengaturan penyedia akun lain, pastikan permintaan terautentikasi sebagai pengguna tepat.
• Jika akun non-admin hasil upgrade pernah menyimpan nilai routing, gunakan Reset untuk plugin tersebut. Nilai legacy yang diabaikan dihapus agar tidak aktif setelah perubahan peran. Menyimpan/me-reset routing juga menghapus model terdeteksi akun agar katalog stale tidak mengikuti rute lama.
• Permintaan berasal dari backend. Saat Libre WebUI berjalan dalam kontainer, localhost merujuk ke kontainer itu, bukan otomatis mesin host.
• Permintaan penyedia tidak mengikuti redirect. Konfigurasikan URL operasi akhir yang tervalidasi secara langsung.

Chat memakai penyedia yang salah atau menampilkan penyedia tidak tersedia

ID model yang sama dapat ada di Ollama dan lebih dari satu plugin. Sesi Chat saat ini dan preferensi model bawaan menyimpan penyedia terpilih bersama ID model mentah, sehingga entri bernama serupa tetap pilihan independen.

• Jika selector menyatakan penyedia tidak tersedia, aktifkan ulang atau instal ulang plugin tepat tersebut dan pastikan model map masih memuat ID tersimpan.
• Jika penyedia/model sengaja dihapus, pilih pengganti secara eksplisit. Libre WebUI tidak mengalihkan pilihan tepat tersimpan ke model bernama sama dari penyedia lain.
• Sesi dan preferensi lama mungkin tidak memiliki metadata penyedia. Record itu tetap memakai routing legacy berbasis nama karena Libre WebUI tidak dapat menyimpulkan penyedia semula. Selector menampilkannya sebagai "provider not recorded". Pilih ulang entri Ollama atau plugin yang diinginkan agar request berikutnya terikat padanya.
• Entri persona tetap berlabel persona:<id>. Persona baru mencatat Ollama sebagai penyedia backing; sesi persona historis tanpa metadata penyedia tetap kompatibel dengan routing legacy.

Masalah Work

Work tidak ada atau melaporkan Runtime unavailable

Work memerlukan akun terautentikasi saat ini dengan akses Work—administrator, atau pengguna aktif mana pun setelah administrator membuka Work bagi semua pengguna dari tab Manajemen Pengguna di Pengaturan. Runtime kontainernya harus tersedia bagi backend Libre WebUI:

docker info
docker version

Untuk backend Docker bawaan, pastikan Docker berjalan dan pengguna OS yang menjalankan Libre WebUI dapat memanggil WORK_DOCKER_COMMAND terkonfigurasi. Memasang Libre WebUI dengan npx tidak memasang Docker. Jika runtime hilang, Libre WebUI mempertahankan aplikasi lain tersedia dan tidak fallback ke menjalankan perintah model pada host.

File Compose repository mengaktifkan Work dengan memasang socket Docker host. Pada Kubernetes, aktifkan runtime Pod/PVC native dengan nilai Helm work.enabled=true; jangan pasang socket runtime node. Jika deployment Compose masih melaporkan Runtime unavailable, halaman Work menyebut penyebabnya:

Pesan	Penyebab dan perbaikan
The "docker" CLI is not installed…	Image khusus tanpa docker-cli. Gunakan image resmi atau arahkan WORK_DOCKER_COMMAND ke CLI.
No Docker daemon is reachable…	Mount socket dihapus atau daemon host berhenti. Pulihkan mount dalam Compose dan mulai Docker.
The Docker socket is mounted but…cannot open	Group socket berbeda dari kontainer. Atur DOCKER_GID dalam .env (lihat bawah) dan recreate kontainer.
Layar/audio Work tertutup dengan WebSocket 1006 dan mencatat screen is unreachable	Backend dalam kontainer menghubungi loopback miliknya sendiri. Pada Docker Desktop gunakan WORK_DOCKER_PUBLISHED_HOST=host.docker.internal bawaan; pada Docker Engine native atur juga WORK_PREVIEW_BIND ke gateway bridge Docker yang non-publik, lalu recreate Libre WebUI.

Baca group socket melalui kontainer karena host macOS melaporkan nilai berbeda dari yang dilihat kontainer:

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 tersebut memberi kontrol host Docker setara root; tinjau Work: workspace terisolasi untuk memahami dampaknya pada deployment.

Model tidak mendukung alat

Work memerlukan model chat berkemampuan alat. Untuk Ollama, pilih model terpasang yang melaporkan capability tools. Untuk model dari plugin:

• Pastikan plugin chat/completion aktif.
• Pastikan model terpilih ada dalam daftar model terkonfigurasi plugin.
• Pastikan API key tersedia bagi administrator saat ini.
• Pastikan penyedia mendukung tool call untuk model tepat tersebut.

Libre WebUI tidak diam-diam merutekan run Work gagal ke penyedia lain.

Permintaan Work mengembalikan HTTP 429

Instance telah mencapai limit admission tugas atau runtime aktif. Secara bawaan, Libre WebUI mengizinkan dua tugas aktif berbasis kontainer pada instance dan satu per pengguna. Preview berjalan juga memakai kapasitas runtime. Tunggu operasi lain selesai, hentikan preview tak terpakai, atau minta operator meninjau WORK_MAX_ACTIVE_RUNTIMES_* dan WORK_MAX_TASKS_*.

Instalasi package atau akses jaringan gagal

Tugas Work baru memakai jaringan bridge Docker agar proyek hasil generasi dapat download package dan memulai preview. Periksa DNS Docker, konfigurasi proxy, ketersediaan registry, dan output command di Activity. Libre WebUI tidak memasang SSH key host, cloud credentials, profil browser, atau socket Docker ke kontainer tugas.

Preview Work tidak dimulai

• Pastikan server bind ke 0.0.0.0 pada WORK_PREVIEW_PORT (bawaan 4173).
• Biarkan command opsional kosong agar mendeteksi otomatis skrip dev package.json atau index.html biasa, termasuk satu aplikasi nested.
• Jika Work melaporkan banyak aplikasi atau tidak ada entry point didukung, masukkan command development eksplisit proyek pada field command opsional. Command dimulai di /workspace; gunakan cd <app-directory> && ... untuk aplikasi nested.
• Perluas detail error untuk memeriksa output startup.
• Hentikan preview yang ada sebelum memulai command lain yang memerlukan kontainer.

URL preview memakai port loopback yang ditetapkan dinamis. Karena itu browser dan backend Libre WebUI harus berjalan pada mesin yang sama. Browser yang terhubung ke backend remote tidak dapat mencapai preview loopback backend, dan halaman HTTPS dapat memblokir preview HTTP biasa sebagai mixed content.

File workspace tidak dapat dibuka atau disimpan

API file Work menerima file teks UTF-8 hingga 2 MB. Jika file berubah setelah Anda membukanya, reload sebelum save agar tidak menimpa versi lebih baru. Formatting terbatas pada tipe file didukung di bawah 100.000 karakter dan 4.000 baris; syntax highlighting berhenti pada file besar agar editing tetap responsif.

Edit belum disimpan dipertahankan sebagai draf pada browser saat ini. Draf bukan pengganti save ke workspace persistent.

Tugas atau preview dihentikan

Menghentikan run/preview atau restart Libre WebUI menghentikan proses kontainer disposable tetapi mempertahankan volume workspace bernama milik tugas. Buka ulang tugas dan restart preview. Menghapus tugas berbeda: setelah konfirmasi, tugas dan workspace dihapus permanen.

Masalah login dan signup

Pengguna pertama bukan admin

Hanya akun pertama yang dibuat dalam basis data baru menjadi admin. Basis data yang ada mempertahankan pengguna dan peran saat ini.

Error JWT

Tetapkan secret stabil pada produksi:

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

Mengubah JWT_SECRET membuat sesi yang ada tidak valid.

Turnstile memblokir signup

Turnstile aktif hanya jika kedua key tersedia:

TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...

Jika signup tiba-tiba gagal, pastikan site key cocok dengan domain dan secret key valid.

Redirect OAuth gagal

Tetapkan URL callback pada dashboard penyedia dan .env backend:

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

Masalah chat dokumen

Libre WebUI menerima file PDF, Office (DOCX/PPTX/XLSX), Markdown, HTML, kode, dan CSV hingga 10 MB.

Jika pencarian bekerja tetapi retrieval semantik tidak:

1. Instal model embedding seperti nomic-embed-text.
2. Aktifkan embedding di Settings.
3. Buat ulang embedding dari pengaturan dokumen atau API.

ollama pull nomic-embed-text

Pencarian keyword tetap bekerja ketika embedding nonaktif.

Masalah preview artefak

Untuk game atau HTML interaktif, minta model menghasilkan satu file HTML lengkap dan mandiri dengan CSS serta JavaScript inline.

Jika artefak memerlukan input keyboard:

• Klik di dalam preview terlebih dahulu.
• Gunakan tombol Open untuk menjalankannya pada tab browser tersendiri.
• Jangan bergantung pada file lokal yang tidak disertakan dalam respons.

Libre WebUI dapat membundel code block index.html + CSS + JavaScript umum, tetapi HTML mandiri tetap merupakan output paling andal.

Masalah Docker

Kontainer tidak dapat menjangkau Ollama

Gunakan file Compose Ollama eksternal jika Ollama tidak berada dalam stack Compose yang sama:

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

Data tidak persistent

Pasang volume data persistent dan tetapkan DATA_DIR bila perlu. Kunci enkripsi disimpan dalam storage persistent ketika DATA_DIR atau mode Docker digunakan.

Me-reset data lokal

Hentikan aplikasi terlebih dahulu. Lalu backup dan hapus direktori data yang digunakan. Secara bawaan, data development berada di backend/data.

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

Restart backend dan buat akun baru.

Masih buntu

Buka issue dengan:

• versi dan commit Libre WebUI;
• metode instalasi;
• sistem operasi;
• versi Node.js;
• versi Ollama;
• versi Docker dan hasil docker info untuk masalah Work;
• log backend di sekitar kegagalan;
• error console browser;
• model atau penyedia tepat yang digunakan;
• output Work Activity ketika tugas atau preview gagal.