Errores comunes

Más de 15 errores habituales al comenzar con Discord.js y Discord.py

Errores Comunes y Soluciones

1. “Cannot find module 'discord.js'” / “No module named 'discord'”

Causa: La librería no está instalada o el entorno activo es incorrecto. Solución (Discord.js):

# Asegúrate de estar en la carpeta del proyecto
npm install discord.js
rm -rf node_modules package-lock.json && npm install

Solución (Discord.py):

# Activa tu entorno virtual
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows
pip install discord.py
python -c "import discord; print(discord.__version__)"

2. Token inválido o no definido

Causa: El token no se pasa correctamente desde variables de entorno. Solución:

// JS
require('dotenv').config();
console.log(process.env.DISCORD_TOKEN);
const client = new Client({ intents: [...] });
client.login(process.env.DISCORD_TOKEN);

# Py
from dotenv import load_dotenv
import os
load_dotenv()
print(os.getenv('DISCORD_TOKEN'))
bot.run(os.getenv('DISCORD_TOKEN'))

3. Intents faltantes

Causa: No se solicitan los intents necesarios al instanciar el cliente. Solución:

// JS
const { Client, GatewayIntentBits } = require('discord.js');
const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.MessageContent
  ]
});

# Py
intents = discord.Intents.default()
intents.message_content = True
bot = commands.Bot(command_prefix='!', intents=intents)

4. Comandos no se ejecutan tras usar on_message

Causa: Al definir on_message, no se llama a process_commands. Solución:

@bot.event
async def on_message(message):
    await bot.process_commands(message)

O usar listeners:

@bot.listen('on_message')
async def log(message):
    print(message.content)

5. “Missing Permissions” / “Missing Access”

Error	Causa	Solución
Missing Access	Bot no está invitado o falta permiso	Invitar de nuevo con permisos correctos
Missing Permissions	Acción prohibida por roles	Asignar permisos en el servidor
Forbidden (403)	Rol del bot por debajo del objetivo	Subir rol del bot en jerarquía

// JS
if (!message.guild.members.me.permissions.has('KICK_MEMBERS')) {
  return message.reply('No tengo permisos.');
}

# Py
if not ctx.guild.me.guild_permissions.kick_members:
    await ctx.send('Sin permiso para expulsar.')

6. Rate Limit Exceeded (429)

Causa: Exceso de peticiones en corto tiempo. Solución:

client.on('rateLimit', info => {
  console.warn(`Rate limit: ${info.timeout}ms en ${info.route}`);
});

# Py – discord.py gestiona automáticamente, pero evita loops rápidos:
await asyncio.sleep(1)

7. “Cannot send empty message”

Causa: Intentar enviar cadena vacía. Solución:

if (!content.trim()) return channel.send('Contenido vacío.');
await channel.send(content);

if not content.strip():
    return await ctx.send('Contenido vacío.')
await ctx.send(content)

8. Error en embed: objeto embed inválido

Causa: Estructura de embed mal formada. Solución:

const embed = new MessageEmbed()
  .setTitle('Título')
  .setDescription('Descripción')
  .setColor('#0099ff');
channel.send({ embeds: [embed] });

embed = discord.Embed(title='Título', description='Descripción', color=0x0099ff)
await ctx.send(embed=embed)

9. “Unhandled promise rejection” / excepción no capturada

Causa: Promesas fallidas sin .catch(). Solución:

process.on('unhandledRejection', err => console.error(err));
channel.send('Hola').catch(console.error);

@bot.event
async def on_error(event, *args):
    import traceback; traceback.print_exc()

10. Conexión de voz sin reproducir audio

Causa: Falta FFmpeg o permisos. Solución:

# Instala FFmpeg
brew install ffmpeg  # Mac
choco install ffmpeg # Windows

import { createAudioPlayer, createAudioResource, joinVoiceChannel } from '@discordjs/voice';

vc.play(discord.FFmpegPCMAudio('audio.mp3'))

11. Argumentos de comando no capturan espacios

Causa: Firma de comando sin *. Solución:

@bot.command()
async def echo(ctx, *, msg: str):
    await ctx.send(msg)

const args = message.content.split(/ +/).slice(1);
const content = args.join(' ');

12. Error “Cannot read property ... of undefined”

Causa: Acceso a propiedad de objeto null/undefined. Solución:

if (!message.member) return;
console.log(message.member.user.username);

if ctx.guild is None:
    return
member = ctx.guild.get_member(user_id)

13. Eventos duplicados al recargar código

Causa: Se añaden listeners cada vez. Solución: Registrar eventos una única vez y reiniciar el proceso al recargar.

client.removeAllListeners();
client.on('messageCreate', handler);

14. Memory leak por listeners dentro de loops

Causa: Añadir listener repetidas veces. Solución: Mover client.on(...) fuera de bucles.

15. Error de permisos de roles al asignar/quitar

Causa: Bot sin “Manage Roles” o rol mal posicionado. Solución:

await member.roles.add(role).catch(console.error);

await member.add_roles(role)

Asegúrate de que el rol del bot esté por encima en la jerarquía.

16. “Shard timeout” al tener muchos servidores

Causa: Bot superó límite sin sharding. Solución:

const client = new AutoShardedClient({ intents: [...] });

bot = commands.AutoShardedBot(command_prefix='!', intents=intents)

17. Error de certificados SSL al hacer peticiones HTTP

Causa: Node.js no reconoce certificados. Solución:

npm install node-fetch@2

process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';

18. Error “Voice packet too large”

Causa: Fichero de audio muy grande. Solución: Reducir bitrate o fragmentar audio antes de reproducir.

19. Dependency conflict al instalar versiones

Causa: Versiones incompatibles de librerías. Solución:

npm install discord.js@14 @discordjs/voice
pip install discord.py==2.5.1

Verifica release notes de cada librería.

20. Crash inesperado sin logs

Causa: No se manejan excepciones globales. Solución:

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

import logging
logging.basicConfig(level=logging.DEBUG)

21. “Error: getaddrinfo ENOTFOUND gateway.discord.gg gateway.discord.gg:443”

Causa: La conexión a Internet se interrumpe o es inestable. Solución:

• Verifica tu conexión a Internet y restáurala si está caída.

• Considera alojar tu bot en un VPS o servicio de hosting con conexión estable.

• Si usas una red corporativa o escolar, comprueba que no haya restricciones de firewall bloqueando Discord.

22. “Unexpected end of input” (SyntaxError: Unexpected end of input)

Causa: Falta un paréntesis, llave, corchete o comilla de cierre en el código. Solución:

• Emplea un editor de código que resalte pares de caracteres (por ejemplo VS Code, WebStorm).

• Haz clic sobre un paréntesis, llave o comilla para ver su contraparte resaltada y ubicar dónde falta el cierre.

• Revisa especialmente bloques if, function, objetos literales y arrays para asegurar que abren y cierran correctamente.