Por qué tu bot de Discord se apaga o aparece offline

Abres Discord, miras la lista de miembros y tu bot está en gris. O peor: antes se mantenía online y ahora se cae de vez en cuando. Para Discord, "offline" significa una sola cosa: tu bot no tiene una conexión activa y autenticada con el Gateway. Tu trabajo es descubrir por qué esa conexión no existe.

Hay dos escenarios muy distintos. O el proceso murió (el programa dejó de ejecutarse), o el proceso sigue vivo, pero el Gateway rechazó o cortó la conexión. La primera pregunta de cualquier diagnóstico es cuál de los dos tienes, y el log lo responde.

¿Cómo sé si el proceso se cayó o solo perdió la conexión?#

Abre el log de tu hosting (o la terminal, si lo ejecutas en local) y ve al final.

• Si el log termina con un stack trace y el proceso salió, el proceso murió: una excepción, falta de memoria o la máquina se apagó. Mira las secciones de excepciones y memoria.
• Si el proceso sigue corriendo y el log muestra un cierre de conexión con código 4004 o 4014, el Gateway lo rechazó: token o intents.
• Si no hay ningún error y el bot responde a comandos pero se ve offline, revisa si tu código pone la presencia en invisible.

Este paso evita el error más común: tocar el código sin saber cuál es tu causa.

¿El token es inválido o fue restablecido?#

Es la causa número uno de un bot que nunca llegó a conectarse. Los mensajes literales:

Error [TokenInvalid]: An invalid token was provided.

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

A nivel de protocolo, el Gateway cierra la conexión con el código 4004, "The account token sent with your identify payload is incorrect", y no permite reconectar con ese token.

Causas típicas: restableciste el token en el Developer Portal y olvidaste actualizar la variable de entorno, lo copiaste con un espacio o comillas de más, o se filtró y fue regenerado. Genera uno nuevo en la página Bot de la aplicación, guárdalo en una variable de entorno (nunca en el código) y reinicia. Si sospechas una filtración, lee cómo proteger el token del bot.

¿Las intents privilegiadas están desactivadas?#

Si tu código pide GuildMembers, GuildPresences o MessageContent, deben estar activadas en el Developer Portal. Si no, el Gateway cierra la conexión con el código 4014 (intent no permitida) y el bot no llega a conectarse. Los errores habituales:

Error: Used disallowed intents

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

Las versiones más antiguas de discord.js v14 muestran Error [DisallowedIntents]: Privileged intent provided is not enabled or whitelisted. en lugar de Error: Used disallowed intents.

La solución: en el Developer Portal, abre tu aplicación, ve a la página Bot y, en la sección Privileged Gateway Intents, activa las que usa el bot. Luego reinicia. Las aplicaciones con menos de 10.000 usuarios solo necesitan el interruptor; por encima de eso, y en bots verificados (obligatorio a partir de 100 servidores), Discord debe aprobar la intent. El código 4013 es otro problema: el valor numérico de las intents se calculó mal.

Pide solo las intents que usas. En 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);

¿Una excepción no controlada tumba el proceso?#

En Node.js, una excepción o una Promise rechazada sin catch termina el proceso y el bot queda offline sin aviso. Eso explica el bot que "se cae solo" tras horas, cuando un evento poco frecuente activa un camino de código sin probar.

Registra los errores inesperados en lugar de morir en silencio:

process.on("unhandledRejection", (reason) => {
  console.error("Promesa rechazada sin manejar:", reason);
});

process.on("uncaughtException", (error) => {
  console.error("Excepción no capturada:", error);
});

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

Así el proceso sigue vivo ante un error aislado y el stack trace queda en el log. Si el estado del bot pudiera quedar corrupto tras una uncaughtException, lo más seguro es registrar el error y salir a propósito, dejando que un supervisor reinicie el proceso. Lo importante es que la caída deje rastro en el log y que algo vuelva a levantar el bot.

¿El bot se quedó sin memoria?#

Si el log termina de golpe, sin stack trace, sospecha de falta de memoria: el sistema o el contenedor mata el proceso al superar el límite. En los bots, el culpable suele ser una caché que crece sin control (miembros, mensajes, presencias), listas globales que nunca se vacían o el procesamiento de imágenes. Observa el uso de RAM en el tiempo: si sube sin parar hasta la caída, es una fuga o una caché demasiado grande. Limita las cachés del client, elimina lo que no uses y, si el bot de verdad necesita más, aumenta la RAM.

¿Tu máquina o tu hosting apaga el bot?#

Si ejecutas el bot en tu propia computadora, desaparece cuando la PC se suspende, se reinicia o pierde internet. En hostings que suspenden procesos inactivos o limitan las horas de uso, pasa lo mismo sin que toques nada. En ambos casos, la salida es la misma: un bot que debe estar online todo el día necesita un proceso supervisado, que se reinicie solo si se detiene, corriendo en algo que no se apague. Mira por qué el bot se cae cuando apagas la PC y cómo mantener un bot online 24/7.

¿Reiniciar en bucle puede empeorar las cosas?#

Sí. Cada nuevo inicio de sesión en el Gateway cuenta como un IDENTIFY, y Discord limita el bot a 1000 IDENTIFY cada 24 horas, sumando todos los shards. Si el bot se cae y vuelve en bucle, supera ese límite: las sesiones activas se terminan y el token se restablece, con aviso por correo al dueño. Por eso, al corregir una caída, no fuerces reinicios repetidos: lee el error, arregla la causa y reinicia una sola vez. Librerías como discord.js y discord.py ya gestionan la reconexión y la reanudación de sesión (RESUME, que no cuenta como IDENTIFY), así que no escribas tu propio bucle de reconexión.

Cómo hacerlo en Square Cloud#

En Square Cloud, el primer paso del diagnóstico ocurre en el panel. Los logs se ven en tiempo real en el panel, la CLI, VS Code y la app móvil, y las líneas de antes de un reinicio siguen visibles, así que el stack trace de la caída no desaparece cuando la aplicación vuelve. Ahí lees el 4004, el 4014 o la excepción que tumbó el proceso. Si prefieres, pide al asistente de IA del panel que lea esos logs y señale la causa probable.

Cada causa de este artículo tiene un punto de corrección conocido:

• Token o intents: cambia el DISCORD_TOKEN en las variables de entorno de la aplicación, activa las intents en el Developer Portal y reinicia una vez. El cambio se aplica en el siguiente reinicio.
• Excepción: el reinicio automático, activado por defecto en el deploy desde el panel, levanta el bot de nuevo cuando el proceso termina con error.
• Memoria: las métricas de CPU y RAM muestran si el uso sube hasta la caída. Quedarse sin memoria detiene la aplicación, y solo vuelve cuando subes la RAM en sus ajustes y la inicias de nuevo.
• Una máquina que se apaga: el contenedor está siempre encendido, sin modo de suspensión ni regla de inactividad.

Un bot usa desde 256 MB del pool de RAM del plan, y el Hobby cuesta R$12,49 al mes con 1 GB. Consulta los detalles en hosting de bots de Discord.