Native Compliation Support

[MinnDevelopment]

General Troubleshooting

• I have checked for similar issues on the Issue-tracker.
• I have updated to the latest JDA version
• I have checked the branches or the maintainers' PRs for upcoming features.

Feature Request

It should be possible to use JDA for an AOT compiled application. For instance, with Spring Native Image or Quarkus Native Image.

This issue serves as a parent issue for all problems related to native images.

Example Use-Case

Ahead of time compiled applications have a faster startup time in exchange for longer compile time.

[fabmars]

Thanks for this Feature ticket.

After I fixed #3027 on my fork's branch (and also made a custom build of nv-websocket-client), I managed to native compile my Quarkus app/bot with JDA. for the record I am using Mandrel 25.0.2 and Quarkus 3.31.3 with my altered version of JDA based on 6.3.1 on Ubuntu 25.10.

openjdk version "25.0.2" 2026-01-20 LTS
OpenJDK Runtime Environment Temurin-25.0.2+10 (build 25.0.2+10-LTS)
OpenJDK 64-Bit Server VM Temurin-25.0.2+10 (build 25.0.2+10-LTS, mixed mode, sharing)

But there's still a couple of side effects:

1. if one doesn't need the audio features and excludes the module opus-java as I have seen in the docs, GraalVM complains it cannot link Opus anymore. This is expected as it digs in the whole dependency jars hierarchy and still finds net.dv8tion.jda.internal.audio.AudioConnection & Decoder in it, with its tomp2p.opuswrapper.Opus import . I tried the other jar flavors to no avail, AudioConnection & Decoder are always included. So, at this time, one must keep opus to be able to natively compile.

2. My native build crashed at startup with the following error:

2026-02-16 23:57:34,595 ERROR [io.quarkus.runtime.Application] (main) Failed to start application: java.lang.RuntimeException: Failed to start quarkus
[...]
Caused by: org.graalvm.nativeimage.MissingReflectionRegistrationError: Cannot reflectively instantiate the array class 'net.dv8tion.jda.api.entities.User[]'. To allow this operation, add the following to the 'reflection' section of 'reachability-metadata.json' and rebuild the native image:                                                                                                                                                                           
                                                                                                                                                                                                                                                                                                                                                                                                                                                                            
 {                                                                                                                                                                                                                                                                                                                                                                                                                                                                          
   "type": "net.dv8tion.jda.api.entities.User[]"                                                                                                                                                                                                                                                                                                                                                                                                                            
 }                                                                                                                                                                                                                                                                                                                                                                                                                                                                          
                                                                                                                                                                                                                                                                                                                                                                                                                                                                            
The 'reachability-metadata.json' file should be located in 'META-INF/native-image/<group-id>/<artifact-id>/' of your project. For further help, see https://www.graalvm.org/latest/reference-manual/native-image/metadata/#reflection                                                                                                                                                                                                                                        
       at org.graalvm.nativeimage.builder/com.oracle.svm.core.reflect.MissingReflectionRegistrationUtils.reportArrayInstantiation(MissingReflectionRegistrationUtils.java:145)                                                                                                                                                                                                                                                                                              
       at org.graalvm.nativeimage.builder/com.oracle.svm.core.graal.snippets.SubstrateAllocationSnippets.arrayHubErrorStub(SubstrateAllocationSnippets.java:420)                                                                                                                                                                                                                                                                                                            
       at net.dv8tion.jda.internal.utils.cache.AbstractCacheView.<init>(AbstractCacheView.java:50)                                                                                                                                                                                                                                                                                                                                                                          
       at net.dv8tion.jda.internal.utils.cache.SnowflakeCacheViewImpl.<init>(SnowflakeCacheViewImpl.java:27)                                                                                                                                                                                                                                                                                                                                                                
       at net.dv8tion.jda.internal.JDAImpl.<init>(JDAImpl.java:109)                                                                                                                                                                                                                                                                                                                                                                                                         
       at net.dv8tion.jda.api.JDABuilder.build(JDABuilder.java:1768)                                                                                                                                                                                                                                                                                                                                                                                                        
       at inc.mutant.rezbot.BotStartup.jda(BotStartup.java:31) 

The quick solution is given in the stacktrace, but the root cause is the bound to all the (Simple/Snowflake/Member)CacheView(Impl) initializations, like there are in the JDA class, that perform an Array.newInstance(Someclass.class) in the AbstractCacheView file.
Not sure how to do differently at this point (actually yes, but I wanna sleep on it), so for now I added file META-INF/native-image/<group-id>/<artifact-id>/reachability-metadata.json in my Quarkus app, containing all the (array)types initialized that way. As far as I can see, apart from the tests, there's no other reflection code.

{
  "reflection": [
    {
      "type": "net.dv8tion.jda.api.entities.User[]"
    },
    {
      "type": "net.dv8tion.jda.api.entities.Role[]"
    },
    {
      "type": "net.dv8tion.jda.api.entities.Guild[]"
    },
    {
      "type": "net.dv8tion.jda.api.entities.Member[]"
    },
    {
      "type": "net.dv8tion.jda.api.entities.ScheduledEvent[]"
    },
    {
      "type": "net.dv8tion.jda.api.entities.ThreadMember[]"
    },
    {
      "type": "net.dv8tion.jda.api.entities.channel.Channel[]"
    },
    {
      "type": "net.dv8tion.jda.api.entities.channel.forums.ForumTag[]"
    },
    {
      "type": "net.dv8tion.jda.api.entities.channel.middleman.GuildChannel[]"
    },
    {
      "type": "net.dv8tion.jda.api.entities.emoji.RichCustomEmoji[]"
    },
    {
      "type": "net.dv8tion.jda.api.entities.sticker.GuildSticker[]"
    },
    {
      "type": "net.dv8tion.jda.api.managers.AudioManager[]"
    },
    {
      "type": "net.dv8tion.jda.internal.entities.GuildVoiceStateImpl[]"
    },
    {
      "type": "net.dv8tion.jda.internal.entities.MemberPresenceImpl[]"
    }
  ]
}

and it worked! My whole Quarkus bot native compiles in 5 minutes-ish (on a 20-core CPU, cough).

Build artifacts:
 /home/fabien/workspace/perso/xyz-bot/build/xyz-bot-1.1.1-native-image-source-jar/build-artifacts.json (build_info)
 /home/fabien/workspace/perso/xyz-bot/build/xyz-bot-1.1.1-native-image-source-jar/xyz-bot-1.1.1-runner (executable)
 /home/fabien/workspace/perso/xyz-bot/build/xyz-bot-1.1.1-native-image-source-jar/xyz-bot-1.1.1-runner-build-output-stats.json (build_info)
========================================================================================================================
Finished generating 'xyz-bot-1.1.1-runner' in 5m 16s.
Base image 'quay.io/quarkus/ubi9-quarkus-micro-image:2.0' does not use a specific image digest - build may not be reproducible

BUILD SUCCESSFUL in 5m 59s
12 actionable tasks: 5 executed, 7 up-to-date
Consider enabling configuration cache to speed up this build: https://docs.gradle.org/9.3.1/userguide/configuration_cache_enabling.html
2026-02-17 01:07:11,101 WARN  [io.smallrye.common.process] (process-waiter-"gradlew"-217474) SRCOM05000: Command /home/fabien/workspace/perso/xyz-bot/gradlew (pid 217474) completed successfully but logged on stderr:
        WARNING: A restricted method in java.lang.System has been called
        WARNING: java.lang.System::load has been called by net.rubygrapefruit.platform.internal.NativeLibraryLoader in an unnamed module (file:/home/fabien/.gradle/wrapper/dists/gradle-9.3.1-bin/23ovyewtku6u96viwx3xl3oks/gradle-9.3.1/lib/native-platform-0.22-miles
        WARNING: Use --enable-native-access=ALL-UNNAMED to avoid a warning for callers in this module
        WARNING: Restricted methods will be blocked in a future release unless native access is enabled                        

~/workspace/perso/xyz-bot  ./build/xyz-bot-1.1.1-runner                                                                                                                                               
__  ____  __  _____   ___  __ ____  ______ 
 --/ __ \/ / / / _ | / _ \/ //_/ / / / __/ 
 -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \   
--\___\_\____/_/ |_/_/|_/_/|_|\____/___/   
2026-02-17 01:07:16,716 INFO  [net.dv8tion.jda.api.JDA] (main) Login Successful!
2026-02-17 01:07:16,720 INFO  [io.quarkus] (main) xyz-bot 1.1.1 native (powered by Quarkus 3.31.3) started in 0.304s. Listening on: http://0.0.0.0:80802026-02-17 01:07:16,720 INFO  [io.quarkus] (main) Profile prod activated.                     2026-02-17 01:07:16,720 INFO  [io.quarkus] (main) Installed features: [cdi, config-yaml, hibernate-validator, langchain4j, langchain4j-ollama, langchain4j-redis, qute, redis-client, rest, rest-client, rest-client-jackson, rest-jackson, smallrye-context-propagation, vertx]
2026-02-17 01:07:16,927 INFO  [net.dv8tion.jda.internal.requests.WebSocketClient] (JDA MainWS-WriteThread) Connected to WebSocket
2026-02-17 01:07:17,126 INFO  [net.dv8tion.jda.api.JDA] (JDA MainWS-ReadThread) Finished Loading!

Overall pretty straightforward, just time consuming.

[freya022]

I believe you can use --allow-incomplete-classpath for the missing Opus classes, until #2997 is merged.

And for any classes which are "unsafe" to initialize at built time, why can you not make them initialized at run time? It would at least help you get around the issue from the websocket library.