Pular para o conteúdo
EntrarCriar minha VPS

Chatwoot não inicia: erros comuns e como resolver

Quando o Chatwoot não inicia, as causas mais frequentes são: Redis não pronto quando o Rails sobe, SECRET_KEY_BASE não definida, migração de banco pendente ou PostgreSQL com senha incorreta. O log do container revela a causa em quase todos os casos, veja como diagnosticar e corrigir cada uma.

Verificar os logs primeiro

Antes de qualquer correção, leia o que o container está reportando. O erro é sempre registrado nas primeiras linhas do log ao tentar iniciar:

bash
# Logs do container Chatwoot (Rails)
docker compose logs chatwoot_rails --tail=50

# Logs do worker Sidekiq
docker compose logs chatwoot_sidekiq --tail=30

# Status de todos os containers do stack
docker compose ps

Causa 1: SECRET_KEY_BASE não configurada

O Rails exige uma chave secreta para assinar cookies e tokens. Sem ela o Chatwoot recusa iniciar com "ArgumentError: secret_key_base is blank":

bash
# Gerar uma chave segura
openssl rand -hex 64

# Adicionar ao .env do docker-compose
SECRET_KEY_BASE=sua_chave_gerada_acima

# Confirmar que o arquivo .env está sendo lido
docker compose config | grep SECRET_KEY_BASE

Causa 2: Redis não está pronto

O Chatwoot usa Redis para ActionCable (websockets) e fila de jobs (Sidekiq). Se o Redis sobe depois do Rails, o Chatwoot falha com "Redis::CannotConnectError". Adicione depends_on com healthcheck:

yaml
services:
  redis:
    image: redis:7-alpine
    restart: always
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5

  rails:
    image: chatwoot/chatwoot:latest
    restart: always
    depends_on:
      redis:
        condition: service_healthy
      postgres:
        condition: service_healthy

Causa 3: migração de banco pendente

Após atualizar a imagem do Chatwoot, o banco pode ter migrações pendentes. O Rails para com "ActiveRecord::PendingMigrationError". Execute as migrações manualmente:

bash
# Rodar migrações pendentes
docker compose exec rails bundle exec rails db:migrate

# Verificar status das migrações
docker compose exec rails bundle exec rails db:migrate:status

# Em caso de primeiro deploy (banco vazio)
docker compose exec rails bundle exec rails db:create db:migrate db:seed

Causa 4: URL ou porta incorreta no FRONTEND_URL

O Chatwoot precisa que FRONTEND_URL seja a URL pública e acessível. Uma URL incorreta causa falha no WebSocket e no carregamento do painel:

bash
# No .env, definir a URL pública (sem barra no final)
FRONTEND_URL=https://chat.seudominio.com.br

# Reconstruir o container após alterar variáveis
docker compose down
docker compose up -d

# Verificar se o painel carrega
curl -I https://chat.seudominio.com.br

Não quer configurar manualmente?

Implante o Chatwoot em menos de 5 minutos com a Runstack. Infraestrutura da OPEN Datacenter, com servidores em São Paulo.

Criar minha VPSVer apps prontos

Perguntas frequentes

docker compose exec rails bundle exec rails c, depois no console: user = SuperAdmin.first; user.update(password: "nova_senha_aqui"); user.save!. Alternativamente, use o reset de senha pela tela de login se o e-mail SMTP estiver configurado.

docker compose logs chatwoot_rails --tail=100 mostra a causa. Problemas comuns: variável de ambiente inválida, porta já ocupada (3000), banco sem espaço em disco. Use docker stats para verificar uso de memória, o Chatwoot precisa de pelo menos 1 GB de RAM livre.

Puxe a nova imagem (docker compose pull), pare os containers (docker compose down), suba novamente (docker compose up -d) e rode as migrações (docker compose exec rails bundle exec rails db:migrate). Os volumes com banco e arquivos persistem entre atualizações.

Principais pontos: aumentar workers do Sidekiq (SIDEKIQ_CONCURRENCY=10 no .env), garantir pelo menos 2 GB RAM para o container Rails, e usar Redis com persistência desabilitada (--save "" no comando do Redis) para menor latência.

O stack completo (Rails + Sidekiq + PostgreSQL + Redis) precisa de pelo menos 2 GB de RAM. Com tráfego moderado (10+ agentes simultâneos), 4 GB é mais confortável. O container Rails (Puma) é o mais pesado, o Sidekiq fica em torno de 200–400 MB.

Continue lendo