Skip to main content

​
Connection Issues

Symptoms:
Exception in thread "main" net.dv8tion.jda.api.exceptions.InvalidTokenException
Causes:
  • Token is incorrect or expired
  • Token has extra whitespace or characters
  • Using user token instead of bot token
Solutions:
  1. Verify your token in the Discord Developer Portal
  2. Regenerate the token if necessary
  3. Ensure no extra spaces or quotes in your token string:
String token = "YOUR_TOKEN_HERE"; // No spaces!
JDABuilder.createDefault(token).build();
  1. Make sure you’re using the bot token, not the client secret
Symptoms:
  • Bot connects then immediately disconnects
  • Repeated reconnection attempts
  • Gateway timeout errors
Causes:
  • Network connectivity issues
  • Firewall blocking WebSocket connections
  • Invalid proxy configuration
  • Rate limiting from Discord
Solutions:
  1. Check your internet connection and firewall settings
  2. Ensure WebSocket connections (wss://) are allowed
  3. If using a proxy, configure it properly:
JDABuilder.createDefault(token)
    .setProxy(new Proxy(Proxy.Type.HTTP, 
        new InetSocketAddress("proxy.example.com", 8080)))
    .build();
  1. Avoid multiple rapid connection attempts (respect rate limits)
  2. Enable debug logging to see detailed connection info:
<!-- logback.xml -->
<logger name="net.dv8tion.jda" level="DEBUG"/>
Symptoms:
  • Bot appears offline in Discord without warning
  • No error messages in logs
  • JVM still running
Causes:
  • Thread pool exhaustion
  • Unhandled exceptions in event listeners
  • Memory leaks
  • Network issues
Solutions:
  1. Add proper error handling in event listeners:
@Override
public void onMessageReceived(MessageReceivedEvent event) {
    try {
        // Your code here
    } catch (Exception e) {
        logger.error("Error handling message", e);
    }
}
  1. Configure custom thread pool if needed:
JDABuilder.createDefault(token)
    .setCallbackPool(Executors.newFixedThreadPool(10))
    .build();
  1. Monitor memory usage and optimize caching
  2. Implement reconnect listeners to log disconnections

​
Intent and Cache Issues

Symptoms:
  • event.getMessage().getContentRaw() returns empty string
  • Message content is blank even though message exists
Cause: Missing MESSAGE_CONTENT privileged intentSolutions:
  1. Enable the intent in Discord Developer Portal:
    • Go to your application
    • Navigate to “Bot” section
    • Enable “Message Content Intent”
  2. Add the intent to your code:
JDABuilder.createDefault(token)
    .enableIntents(GatewayIntent.MESSAGE_CONTENT)
    .build();
  1. For verified bots with 100+ servers, you may need to apply for intent approval
Symptoms:
  • guild.getMembers() returns empty or incomplete list
  • guild.getMemberById() returns null for existing members
  • Member count shows as 0 or 1
Causes:
  • Missing GUILD_MEMBERS intent
  • Member cache disabled
  • Member chunking not enabled
Solutions:
  1. Enable required intent and configure caching:
JDABuilder.createDefault(token)
    .enableIntents(GatewayIntent.GUILD_MEMBERS)
    .setMemberCachePolicy(MemberCachePolicy.ALL)
    .setChunkingFilter(ChunkingFilter.ALL)
    .build();
  1. For large bots, use selective caching:
JDABuilder.createDefault(token)
    .enableIntents(GatewayIntent.GUILD_MEMBERS)
    .setMemberCachePolicy(MemberCachePolicy.VOICE.or(MemberCachePolicy.OWNER))
    .build();
  1. Fetch members on-demand if caching is disabled:
guild.retrieveMemberById(userId).queue(member -> {
    // Use member here
});
Symptoms:
  • onUserUpdateOnlineStatus not firing
  • User activities not updating
Cause: Missing GUILD_PRESENCES intentSolutions:
  1. Enable the privileged intent in Developer Portal
  2. Add to your bot configuration:
JDABuilder.createDefault(token)
    .enableIntents(GatewayIntent.GUILD_PRESENCES)
    .build();
GUILD_PRESENCES is a privileged intent and requires approval for verified bots

​
Command and Interaction Issues

Symptoms:
  • Commands registered but not visible in Discord
  • / menu doesn’t show your bot’s commands
Causes:
  • Commands not registered with Discord
  • Using guild commands but checking different guild
  • Caching delay for global commands
Solutions:
  1. Ensure commands are registered:
jda.updateCommands()
    .addCommands(
        Commands.slash("ping", "Check bot latency")
    )
    .queue();
  1. For testing, use guild-specific commands (instant update):
guild.updateCommands()
    .addCommands(Commands.slash("test", "Test command"))
    .queue();
  1. Global commands can take up to 1 hour to propagate
  2. Check bot has applications.commands scope
Symptoms:
ErrorResponseException: 10062: Unknown interaction
Cause: Response sent more than 3 seconds after receiving interactionSolutions:
  1. Always acknowledge interactions immediately:
@Override
public void onSlashCommandInteraction(SlashCommandInteractionEvent event) {
    event.deferReply().queue(); // Acknowledge immediately
    
    // Do long-running task
    performLongTask().thenAccept(result -> {
        event.getHook().sendMessage(result).queue();
    });
}
  1. Use deferReply(true) for ephemeral responses
  2. For very long operations, send immediate response and update later
Symptoms:
  • Clicking buttons/menus does nothing
  • “This interaction failed” message
Causes:
  • Component IDs don’t match handler
  • No event listener registered
  • Component expired (messages older than 15 minutes)
Solutions:
  1. Ensure listener is registered:
jda.addEventListener(new ButtonListener());
  1. Match component IDs correctly:
// Creating button
Button button = Button.primary("accept", "Accept");

// Handling button
@Override
public void onButtonInteraction(ButtonInteractionEvent event) {
    if (event.getComponentId().equals("accept")) {
        event.reply("Accepted!").queue();
    }
}
  1. For persistent buttons, use unique IDs and store state in database

​
Audio Issues

Symptoms:
  • Bot appears in voice channel
  • No sound is heard
  • No errors in console
Causes:
  • Missing audio implementation (DAVE Protocol)
  • Audio send system not configured
  • Bot muted or volume at 0
Solutions:
  1. Add DAVE Protocol implementation dependency:
dependencies {
    implementation("net.dv8tion:JDA:6.3.1")
    implementation("dev.arbjerg:lavaplayer:2.2.2")
}
  1. Check if bot is server muted in Discord
  2. Verify audio sending is working:
AudioManager audioManager = guild.getAudioManager();
audioManager.setSendingHandler(yourAudioSendHandler);
  1. See Making a Music Bot guide
Symptoms:
  • Audio plays but skips or stutters
  • Robotic or distorted sound
Causes:
  • GC pauses interrupting audio thread
  • CPU overload
  • Network issues
Solutions:
  1. Use udpqueue to avoid GC pauses:
JDABuilder.createDefault(token)
    .setAudioSendFactory(new NativeAudioSendFactory())
    .build();
  1. Optimize JVM garbage collection settings
  2. Reduce bot workload during playback
  3. Use Lavalink for distributed audio processing
Symptoms:
InsufficientPermissionException: VOICE_CONNECT
Cause: Bot lacks required permissionsSolutions:
  1. Check bot has VOICE_CONNECT permission:
if (voiceChannel.getGuild().getSelfMember()
        .hasPermission(voiceChannel, Permission.VOICE_CONNECT)) {
    audioManager.openAudioConnection(voiceChannel);
}
  1. Verify role permissions in Discord server settings
  2. Check channel-specific permission overrides

​
Performance Issues

Causes:
  • Aggressive caching
  • Memory leaks in event handlers
  • Large message/embed caching
Solutions:
  1. Use lighter cache configuration:
JDABuilder.createLight(token)
    .setEnabledCacheFlags(EnumSet.noneOf(CacheFlag.class))
    .build();
  1. Disable unnecessary caches:
JDABuilder.createDefault(token)
    .disableCache(CacheFlag.ACTIVITY, CacheFlag.CLIENT_STATUS)
    .build();
  1. Monitor heap usage and tune JVM parameters
  2. Use weak references for temporary data
Symptoms:
  • Commands take long to respond
  • RateLimitedException errors
  • 429 HTTP responses
Causes:
  • Hitting Discord API rate limits
  • Too many requests in short time
  • Inefficient request patterns
Solutions:
  1. JDA handles rate limits automatically - don’t override
  2. Batch requests when possible:
RestAction.allOf(actions).queue();
  1. Use efficient caching to reduce API calls
  2. Implement request queuing for burst operations
  3. Review logs for rate limit warnings

​
Build and Dependency Issues

Symptoms:
java.lang.NoClassDefFoundError: org/slf4j/Logger
Cause: Missing dependenciesSolutions:
  1. Add SLF4J implementation:
dependencies {
    implementation("net.dv8tion:JDA:6.3.1")
    implementation("ch.qos.logback:logback-classic:1.4.11")
}
  1. If using Maven, ensure all dependencies are included
  2. For shaded JARs, verify dependency inclusion
Symptoms:
  • Build fails with dependency resolution errors
  • Runtime errors with conflicting classes
Solutions:
  1. Use dependency management:
configurations.all {
    resolutionStrategy {
        force("com.squareup.okhttp3:okhttp:4.12.0")
    }
}
  1. Check for conflicting transitive dependencies
  2. Update all JDA-related libraries together
Cause: JDA requires Java 8 or higherSolutions:
  1. Ensure Java 8+ is installed: java -version
  2. Set Gradle/Maven to use Java 8+:
java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(17))
    }
}

​
Getting More Help

If your issue isn’t listed here:
  1. Search existing issues: GitHub Issues
  2. Check the FAQ: JDA FAQ
  3. Ask on Discord: JDA Discord Server
  4. Review documentation: JDA Wiki
When reporting issues, always include:
  • JDA version
  • Java version
  • Complete error stack trace
  • Minimal reproducible code example

Build docs developers (and LLMs) love

Get started for freeTalk to us