Solução de problemas

Comece pela camada que falha: navegador, frontend, backend, Ollama, plugin do provedor ou rede da implantação.

Verificações rápidas

# 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

No desenvolvimento, o frontend costuma estar em http://localhost:5173 e o backend em http://localhost:3001. O fluxo npx libre-webui serve em http://localhost:8080.

Libre WebUI não inicia

Verifique Node e dependências

node --version
npm install
npm run dev

É necessário Node.js 22.22 ou mais recente.

Porta em uso

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

Pare o processo antigo ou use outra porta.

Backend não consegue gravar dados

O backend usa DATA_DIR quando definido, senão backend/data. Execuções pelo código-fonte resolvem um valor relativo a partir do diretório do backend: DATA_DIR=./data escolhe backend/data, enquanto o histórico DATA_DIR=./backend/data escolhe backend/backend/data. Garanta permissão de escrita. Sem valor, o Libre preserva o diretório histórico se for o único armazenamento. Se ambos tiverem dados, pare, faça backup e escolha ou migre conscientemente; nunca mescla nem copia bancos divergentes.

Os endpoints distinguem processo vivo de aplicação utilizável:

• /health e /health/live retornam 200 quando o processo serve HTTP. Provedores opcionais não afetam.
• /health/ready retorna 503 quando banco, esquema, armazenamento ou dependência registrada obrigatória está indisponível. Não espera provedores opcionais e omite detalhes públicos.
• /health/deep executa integridade SQLite e chaves estrangeiras em worker limitado e agrega sondagens opcionais como Ollama. Falha opcional vira aviso. Exige token Bearer de administrador e não serve como sondagem frequente.

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

Navegador não alcança o backend

No desenvolvimento, o frontend usa VITE_API_BASE_URL ou recorre ao backend de desenvolvimento.

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

VITE_WS_BASE_URL é opcional, mas define a base de Chat e terminal Work. Use URL absoluta ws: ou wss:; prefixos como wss://example.com/libre são aceitos. Não inclua credenciais, consulta ou fragmento. Reinicie/recompile após alterar variável Vite.

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

Para telefone, LAN ou Tailscale, não use localhost no telefone; use o IP do computador e execute:

npm run dev:host

Isso disponibiliza o frontend na porta 8080 e faz proxy do tráfego de API e WebSocket para o backend local na porta 3001. Somente a porta 8080 precisa estar acessível a partir do outro dispositivo. Se VITE_API_BASE_URL ou VITE_WS_BASE_URL estiver definido em frontend/.env, garanta que essas URLs sejam acessíveis a partir do outro dispositivo, ou remova-as para usar o proxy do servidor de desenvolvimento.

Chat não transmite atrás de proxy reverso

O sintoma típico é enviar sem receber resposta, com falha WebSocket no console. Confirme upgrades e conexões longas.

Quando CORS_ORIGIN ou BASE_URL está definido, o Origin do navegador é comparado. Defina ao menos um remotamente; sem ambos, é permissivo para desenvolvimento. Electron e outros podem omitir Origin, mas ainda trocam Authorization por ticket único curto. Mantenha backend sob TLS e os mesmos controles da API.

Para host público:

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

Os exemplos nginx/Caddy supõem proxy no host Docker e Libre na porta 8080. Se o proxy entra na rede Compose, use libre-webui:3001.

nginx

nginx precisa encaminhar cabeçalhos e timeout longo:

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

Valide com nginx -t e recarregue.

Caddy

reverse_proxy suporta WebSocket por padrão:

chat.example.com {
    reverse_proxy 127.0.0.1:8080
}

Traefik

Traefik também trata upgrades. Na mesma rede:

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'

Se cair depois, confira timeout ocioso de proxies/load balancers. No Traefik, ajuste transport.respondingTimeouts.

Ollama não é detectado

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

URL personalizada no backend:

OLLAMA_BASE_URL=http://localhost:11434

Se Libre está no Docker e Ollama no host, use o Compose externo ou defina OLLAMA_BASE_URL com um endereço acessível do contêiner.

Problemas ao baixar modelos

ollama pull gemma4:12b

Se falhar no terminal, o problema está fora do Libre.

Modelos na nuvem

Use o filtro Ollama Cloud. O Libre normaliza sufixos necessários; não é preciso adicionar :cloud manualmente.

Usuário não consegue baixar

Administradores podem proibir downloads. Confira a configuração se um usuário vê, mas não instala.

Chat lento ou com falha

• Use modelo menor.
• Confira ollama ps.
• Reduza contexto e máximo de tokens.
• Confirme RAM/VRAM.
• Em plugins, confirme chave e cota.

Geração de imagens OpenAI indisponível

• Ative o provedor OpenAI. Salve chave do usuário ou configure OPENAI_API_KEY confiável.
• Ative a geração e escolha um GPT Image anunciado.
• Prefira gpt-image-2; IDs anteriores são compatibilidade e depreciados.
• Deixe image_endpoint vazio salvo endpoint compatível. /responses e /chat/completions não processam Image API.
• Se houver rejeição com chave e cota válidas, confirme elegibilidade da organização.

A disponibilidade usa credencial do usuário atual ou fallback confiável. Chave em outra conta não expõe modelos.

Problemas de endpoint de provedor

Se um provedor compatível com OpenAI recebe solicitações no caminho errado, confira Configurações → Plugins:

• Escolha Chat Completions para /chat/completions ou Responses para /responses.
• Informe a raiz, como https://provider.example/v1, em Base URL.
• Deixe API Path vazio para o padrão ou informe caminho iniciado por barra.
• Um endpoint legado realmente personalizado tem maior prioridade; limpe-o ao voltar a Base URL/API Path. Valores iguais ao padrão antigo do manifesto são ignorados após atualização. Sufixo /chat/completions ou /responses também determina o formato.

JSON importado suporta provedores com formato OpenAI Chat Completions, OpenAI Responses, Anthropic ou Gemini. Payload, streaming, ferramentas ou resposta proprietários exigem adaptador; mudar apenas endpoint não traduz.

URLs podem ser HTTP ou HTTPS. HTTP não criptografa credenciais e tráfego; reserve a gateway auto-hospedado em rede confiável. Base URLs não podem conter consulta ou fragmento, e caminhos relativos não podem conter traversal literal/repetidamente codificado, consulta ou fragmento. Codificação excessiva que não estabiliza é rejeitada.

Atualizar modelos troca sufixos conhecidos, inclusive /responses, por /models. Ativação, atualização e substituições usam endpoint e chave do usuário. Salvar/remover chave e redefinir conexão também atualiza; geração não. IDs são por usuário e não mudam JSON. Se não houver rota compatível, configure model_map.

Solicitações de descoberta, Chat, Work, imagem, embedding e TTS não seguem redirecionamentos. Configure o destino final para que Authorization não pule a um destino não validado.

Se Work informar mudança de roteamento durante execução, termine a atualização e inicie outra. Ele para antes da próxima solicitação para não reproduzir estado anterior em outro modo, endpoint ou chave.

Solicitações saem do backend; em contêiner localhost é o Libre WebUI, não o host. Em Compose/Kubernetes use DNS do serviço, como http://ai-gateway:8080/v1. Use http://host.docker.internal:8080/v1 somente quando disponível. HTTP é texto simples mesmo em nome privado.

Imagem, substituições e chaves também são resolvidas para o usuário atual. Confira a autenticação se parecer usar outra conta.

Regras adicionais:

• Somente administrador altera roteamento. Definições e conexões são da instância; usuários comuns ainda salvam geração, credenciais e ativação.
• Em endpoint ou api_url, informe o URL completo com operação, como https://provider.example/v1/chat/completions. Raiz vai apenas em base_url, com api_mode e api_path.
• Aceitam-se URLs HTTP(S) absolutos; HTTP somente em rede confiável.
• Substituição vazia usa a definição; inválida é rejeitada, não enviada ao padrão.
• Chave ambiental só é usada quando definição incluída não shadowed preserva endpoint raiz, autenticação, capacidades, seletores e padrões confiáveis. Importadas, graváveis com ID incluído e rotas personalizadas exigem credencial da mesma conta. Somente chave ambiental faz o provedor ficar indisponível.
• Definições personalizadas antigas ficam em quarentena; reimporte como administrador e reative por usuário. Editar JSON aprovado diretamente coloca em quarentena; use instalação/atualização para registrar caminho e hash.
• Credenciais salvas vinculam-se à rota, autenticação, definição e origem. Após mudança, salve novamente. Credencial antiga sem vínculo só migra na rota incluída exata.
• api_url pode ser alias legado; endpoint prevalece. Use models_endpoint para URL completa da lista, validada e sem redirects.
• Ative após salvar endpoint/credencial. A ativação deriva /models e usa a credencial do usuário, salvo models_endpoint. Mudanças de conexão também atualizam e aguardam antes de recarregar. Cada conta ativa separadamente.
• Em Configurações → Plugins, use Atualizar modelos. A tabela é somente leitura. Falha transitória preserva catálogo anterior ou model_map, portanto completar a verificação não prova saúde.
• Descoberta exige array data compatível. Catálogos são por usuário. Ativação normal preserva o anterior; mudar conexão limpa primeiro e recorre a model_map.
• Imagem também usa usuário atual.
• Se uma conta não administrativa guardou rota antes da atualização, use Redefinir. O valor ignorado e catálogo antigo são removidos.
• No contêiner, localhost é o contêiner.
• Solicitações não seguem redirecionamentos.

Chat usa provedor errado ou o mostra indisponível

O mesmo ID pode existir no Ollama e em vários plugins. Sessões e preferências atuais salvam provedor e ID bruto.

• Se indisponível, reative/reinstale o plugin exato e confira o mapa.
• Se removido, escolha substituto; o Libre não redireciona para homônimo.
• Registros antigos podem não ter metadados e continuam com roteamento por nome, aparecendo como "provedor não registrado". Selecione uma entrada para fixar.
• Personas mantêm persona:<id>; novas registram Ollama como base, antigas continuam compatíveis.

Problemas do Work

Work ausente ou runtime indisponível

É preciso uma conta autenticada com acesso: administrador ou usuário ativo após abertura pela aba Gerenciamento de Usuários em Configurações. O runtime deve estar disponível ao backend:

docker info
docker version

No Docker padrão, confirme daemon e permissão do usuário para WORK_DOCKER_COMMAND. npx não instala Docker. Sem runtime, o restante continua e comandos nunca são executados diretamente no host.

Compose monta o socket. No Kubernetes, ative work.enabled=true e não monte socket do nó. Se Compose ainda informar indisponível:

Mensagem	Causa e solução
The "docker" CLI is not installed…	Imagem personalizada sem docker-cli; use a oficial ou WORK_DOCKER_COMMAND.
No Docker daemon is reachable…	Montagem removida ou daemon parado; restaure e inicie.
The Docker socket is mounted but…cannot open	Grupo diferente; defina DOCKER_GID no .env e recrie.
Tela/áudio do Work fecha com WebSocket 1006 e registra screen is unreachable	O backend em contêiner está discando para o próprio loopback. No Docker Desktop, use o WORK_DOCKER_PUBLISHED_HOST=host.docker.internal que já vem configurado; no Docker Engine nativo, defina também WORK_PREVIEW_BIND com o gateway não público da bridge do Docker e recrie o Libre WebUI.

Leia o grupo por um contêiner porque macOS mostra outro valor:

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

O socket concede controle equivalente a root. Consulte Work: espaços isolados.

Modelo sem suporte a ferramentas

Escolha modelo Ollama que anuncie tools. Em plugin:

• plugin chat/completion ativo;
• modelo na lista;
• chave disponível ao administrador;
• suporte a ferramentas no modelo exato.

Não há fallback silencioso.

Solicitação Work retorna HTTP 429

Um limite de tarefas ou runtimes foi atingido. Por padrão, são duas tarefas ativas na instância e uma por usuário. Prévia também ocupa capacidade. Aguarde, pare prévia ou revise WORK_MAX_ACTIVE_RUNTIMES_* e WORK_MAX_TASKS_*.

Instalação de pacote ou rede falha

Tarefas novas usam rede bridge para baixar pacotes. Confira DNS, proxy, registro e saída em Atividade. Não são montados SSH, credenciais de nuvem, perfis de navegador nem socket Docker.

Prévia Work não inicia

• O servidor deve escutar 0.0.0.0 em WORK_PREVIEW_PORT (padrão 4173).
• Deixe comando vazio para detectar package.json dev ou index.html, inclusive um app aninhado.
• Se houver vários apps ou nenhum ponto, informe comando explícito. Começa em /workspace; use cd <app-directory> && ....
• Expanda os detalhes.
• Pare prévia existente antes de outro comando.

URLs usam porta loopback dinâmica. Navegador e backend precisam estar na mesma máquina; navegador remoto não alcança loopback, e HTTPS pode bloquear HTTP como mixed content.

Arquivo não abre ou salva

A API aceita texto UTF-8 até 2 MB. Se mudou após abrir, recarregue antes de salvar. Formatação limita-se a tipos compatíveis com menos de 100.000 caracteres e 4.000 linhas; destaque pausa em arquivos grandes.

Rascunhos no navegador não substituem salvar no espaço persistente.

Tarefa ou prévia interrompida

Parar execução/prévia ou reiniciar remove processos descartáveis, mas preserva o volume. Reabra e reinicie. Excluir é diferente: remove permanentemente tarefa e espaço após confirmação.

Problemas de login e cadastro

Primeiro usuário não é administrador

Somente a primeira conta em banco novo vira admin. Bancos existentes mantêm papéis.

Erros JWT

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

Alterar JWT_SECRET invalida sessões.

Turnstile bloqueia cadastro

TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...

Só é ativado com ambas. Confira domínio e segredo.

Redirecionamentos OAuth falham

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

Problemas no chat com documentos

Aceita PDF, Office, Markdown, HTML, código e CSV até 10 MB. Se a busca funciona, mas semântica não:

1. Instale nomic-embed-text.
2. Ative embeddings.
3. Regenere.

ollama pull nomic-embed-text

Palavras-chave continuam sem embeddings.

Problemas na prévia de artefatos

Para jogos/HTML, peça um arquivo completo com CSS e JavaScript em linha. Se precisar de teclado:

• Clique dentro primeiro.
• Abra em guia própria.
• Não dependa de arquivos locais ausentes.

O Libre pode agrupar index.html + CSS + JavaScript, mas um HTML independente é mais confiável.

Problemas do Docker

Contêiner não alcança Ollama

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

Dados não persistem

Monte volume persistente e defina DATA_DIR se preciso. A chave fica no armazenamento persistente em DATA_DIR ou modo Docker.

Redefinir dados locais

Pare o app, faça backup e remova o diretório em uso. O padrão é backend/data.

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

Reinicie e crie conta nova.

Ainda com problemas

Abra issue com:

• versão e commit
• método de instalação
• sistema operacional
• versão Node.js
• versão Ollama
• versão Docker e docker info em problemas Work
• logs do backend
• erros do console
• modelo/provedor exato
• saída de Atividade quando tarefa/prévia falha