Runstack
    self-hosting/Artigo

    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
    Dica
    Procure por: "SECRET_KEY_BASE", "PG::ConnectionBad", "Redis::CannotConnectError" ou "ActiveRecord::PendingMigrationError" — cada mensagem aponta para uma causa específica abaixo.

    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
    Atenção
    Nunca use a mesma chave em desenvolvimento e produção. Se você rotacionar a chave em produção, todas as sessões de usuário são invalidadas (todos os agentes precisam fazer login novamente).

    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
    Dica
    O db:seed cria o usuário administrador inicial. Após o seed, faça login em /auth/sign_in com super_admin@example.com e altere a senha imediatamente.

    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

    $ runstack deploy --plan starter

    Não quer configurar manualmente?

    Não quer configurar manualmente? Implante o Chatwoot em menos de 3 minutos com a Runstack. Infraestrutura da OPEN DATACENTER, com servidores no Brasil.

    Começar agoraVer planos e preços

    Perguntas frequentes

    Conteúdos relacionados

    VPS para Chatwoot no Brasil →Como instalar o Chatwoot →Chatwoot + WhatsApp com Evolution APIConfigurar SMTP no Chatwoot