Por que meu bot do Discord fica offline (e como resolver)

Você abre o Discord, olha a lista de membros e o bot está cinza. Ou pior: ele ficava online e começou a cair de tempos em tempos. Para o Discord, "offline" significa uma coisa só: não existe uma conexão ativa e autenticada do seu bot com o Gateway. Seu trabalho é descobrir por que essa conexão não existe.

Há dois cenários bem diferentes. Ou o processo morreu (o programa parou de rodar), ou o processo está vivo, mas o Gateway recusou ou derrubou a conexão. A primeira pergunta de qualquer diagnóstico é qual dos dois você tem, e o log responde.

Como saber se o processo caiu ou só perdeu a conexão?#

Abra o log da sua hospedagem (ou o terminal, se roda localmente) e vá até o final.

• Se o log termina com um stack trace e o processo encerrou, é queda de processo: exceção, falta de memória ou a máquina desligou. Veja as seções de exceção e memória.
• Se o processo continua rodando e o log mostra um fechamento de conexão com código 4004 ou 4014, é recusa do Gateway: token ou intents.
• Se não há erro nenhum e o bot responde a comandos mas aparece offline, confira se o código define a presença como invisible.

Esse passo evita o erro mais comum: mexer no código sem saber qual das causas é a sua.

O token está inválido ou foi resetado?#

É a causa número um de um bot que nunca chegou a ficar online. As mensagens literais:

Error [TokenInvalid]: An invalid token was provided.

discord.errors.LoginFailure: Improper token has been passed.

No nível do protocolo, o Gateway fecha a conexão com o código 4004, "The account token sent with your identify payload is incorrect", e não permite reconectar com o mesmo token.

Causas típicas: você resetou o token no Developer Portal e esqueceu de atualizar a variável de ambiente, copiou o token com espaço ou aspas sobrando, ou o token vazou e foi regenerado. Gere um novo na página Bot da aplicação, guarde em variável de ambiente (nunca no código) e reinicie. Se suspeita de vazamento, leia como proteger o token do bot.

As intents privilegiadas estão desligadas?#

Se o seu código pede GuildMembers, GuildPresences ou MessageContent, elas precisam estar ligadas no Developer Portal. Caso contrário, o Gateway fecha a conexão com o código 4014 (intent não permitida) e o bot não conecta. Os erros comuns:

Error: Used disallowed intents

discord.errors.PrivilegedIntentsRequired: Shard ID None is requesting privileged intents that have not been explicitly enabled in the developer portal.

Versões mais antigas do discord.js v14 mostram Error [DisallowedIntents]: Privileged intent provided is not enabled or whitelisted. no lugar de Error: Used disallowed intents.

A correção: no Developer Portal, abra a sua aplicação, vá à página Bot e, na seção Privileged Gateway Intents, ligue as que o bot usa. Depois, reinicie. Aplicações com menos de 10.000 usuários só precisam do interruptor; acima disso, e em bots verificados (exigido a partir de 100 servidores), a intent precisa ser aprovada pelo Discord. Já o código 4013 é outro problema: o valor numérico de intents foi calculado errado.

Peça apenas as intents que o bot usa. Em discord.js v14:

import { Client, GatewayIntentBits } from "discord.js";

const client = new Client({
  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages],
});

await client.login(process.env.DISCORD_TOKEN);

Uma exceção não tratada derruba o processo?#

No Node.js, uma exceção ou uma Promise rejeitada sem catch encerra o processo e o bot fica offline sem aviso. Isso explica o bot que "cai sozinho" depois de horas, quando um evento raro dispara um caminho de código não testado.

Registre os erros inesperados em vez de morrer em silêncio:

process.on("unhandledRejection", (reason) => {
  console.error("Promise rejeitada sem tratamento:", reason);
});

process.on("uncaughtException", (error) => {
  console.error("Exceção não capturada:", error);
});

client.on("error", (error) => console.error("Erro do client:", error));
client.on("shardError", (error) => console.error("Erro de WebSocket:", error));

Isso mantém o processo vivo para um erro isolado e deixa o stack trace no log. Se o estado do bot puder ficar corrompido depois de uma uncaughtException, o mais seguro é registrar o erro e encerrar de propósito, deixando um supervisor reiniciar o processo. O importante é que a queda deixe rastro no log e que algo suba o bot de novo.

O bot ficou sem memória?#

Se o log termina de forma abrupta, sem stack trace, suspeite de falta de memória: o sistema ou o contêiner mata o processo ao passar do limite. Em bots, o vilão costuma ser cache crescendo sem controle (membros, mensagens, presenças), listas globais que nunca são esvaziadas ou processamento de imagem. Veja o uso de RAM ao longo do tempo: se sobe sem parar até a queda, é vazamento ou cache grande demais. Limite os caches do client, remova o que não usa e, se o bot realmente precisa de mais, aumente a RAM.

A máquina ou a hospedagem desliga o bot?#

Se você roda no próprio computador, o bot some quando o PC dorme, reinicia ou perde a internet. Em hospedagens que suspendem processos ociosos ou limitam horas de uso, acontece o mesmo sem você tocar em nada. Nos dois casos, a saída é a mesma: um bot que precisa ficar online o dia todo pede um processo supervisionado, que reinicia sozinho se parar, rodando em algo que não desliga. Veja por que o bot cai quando o PC desliga e como deixar o bot online 24/7.

Reiniciar em loop pode piorar a situação?#

Sim. Cada login novo no Gateway conta como um IDENTIFY, e o Discord limita o bot a 1000 IDENTIFY por período de 24 horas, somando todos os shards. Se o bot cai e volta em loop, estoura esse limite: as sessões ativas são encerradas e o token é resetado, com aviso por e-mail ao dono. Por isso, ao corrigir uma queda, não force reinícios repetidos: leia o erro, conserte a causa e reinicie uma vez. Bibliotecas como discord.js e discord.py já tratam reconexão e retomada de sessão (RESUME), que não conta como IDENTIFY, então não escreva um laço próprio de reconexão.

Como fazer isso na Square Cloud#

Na Square Cloud, o primeiro passo do diagnóstico acontece no painel. Os logs aparecem em tempo real no painel, na CLI, no VS Code e no app de celular, e as linhas de antes de um restart continuam visíveis, então o stack trace da queda não some quando a aplicação volta. É ali que você lê o 4004, o 4014 ou a exceção que derrubou o processo. Se preferir, peça ao assistente de IA do painel que leia esses logs e aponte a causa provável.

Cada causa deste artigo tem um ponto de correção conhecido:

• Token ou intents: troque o DISCORD_TOKEN nas variáveis de ambiente da aplicação, ligue as intents no Developer Portal e reinicie uma vez. A mudança vale no próximo restart.
• Exceção: o reinício automático, ligado por padrão no deploy pelo painel, sobe o bot de novo quando o processo encerra com erro.
• Memória: as métricas de CPU e RAM mostram se o uso sobe até a queda. Um estouro de memória para a aplicação, e ela só volta quando você aumenta a RAM nas configurações e a inicia de novo.
• Máquina que desliga: o container fica sempre ligado, sem modo de suspensão e sem regra de inatividade.

Um bot usa a partir de 256 MB do pool de RAM do plano, e o Hobby custa R$ 12,49 por mês com 1 GB. Veja os detalhes em hospedagem de bots do Discord.