Java bots: JDA and runnable jars

Java servers run a jar. There is no build step on the server: you build the bot on your computer (or in GitHub Actions) into one jar that includes its dependencies, and the server runs java -jar on it.

Versions

Java 17, 21 and 25, chosen at checkout or under Startup, Docker Image. Java 21 is the default. Pick at least the version your jar was built for; newer is fine.

New to JDA? Make a Discord bot in Java goes from an empty folder to this jar.

Build a runnable jar

A normal jar task leaves JDA and your other libraries out, and the bot stops with NoClassDefFoundError. Build a jar with dependencies included:

Gradle

// settings.gradle
rootProject.name = 'yourbot'

// build.gradle
plugins {
    id 'java'
    id 'application'
    id 'com.gradleup.shadow' version '8.3.5'
}

version = '1.0'

repositories { mavenCentral() }

dependencies {
    implementation 'net.dv8tion:JDA:6.7.0'
}

application {
    mainClass = 'com.example.bot.Main'
}

The project name and version are what make the jar yourbot-1.0-all.jar. Then ./gradlew shadowJar, and upload build/libs/yourbot-1.0-all.jar. The JDA version is only an example: use the current one from JDA's releases.

Maven

A pom.xml with the maven-assembly-plugin, the jar-with-dependencies descriptor and your main class in its manifest:

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>yourbot</artifactId>
  <version>1.0</version>

  <properties>
    <maven.compiler.release>21</maven.compiler.release>
  </properties>

  <dependencies>
    <dependency>
      <groupId>net.dv8tion</groupId>
      <artifactId>JDA</artifactId>
      <version>6.7.0</version>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <artifactId>maven-assembly-plugin</artifactId>
        <version>3.7.1</version>
        <configuration>
          <descriptorRefs>
            <descriptorRef>jar-with-dependencies</descriptorRef>
          </descriptorRefs>
          <archive>
            <manifest>
              <mainClass>com.example.bot.Main</mainClass>
            </manifest>
          </archive>
        </configuration>
        <executions>
          <execution>
            <phase>package</phase>
            <goals><goal>single</goal></goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

Run mvn package and upload target/yourbot-1.0-jar-with-dependencies.jar.

Upload and run it

1. Upload the jar in Files, or over SFTP.
2. Leave Bot file empty if it is the only jar: it is found in the top folder, build/libs or target. With several, set it to the right one. The box takes a path from the server's top folder, for example build/libs/yourbot-1.0-all.jar, not only a file name.
3. Restart. The console shows Starting: java -jar yourbot-1.0-all.jar, then your bot's output.

Git deploy pulls files but does not build Java. To deploy from GitHub, have a GitHub Actions workflow build the jar and commit it to a branch the server follows, or upload the jar by hand. With that branch set on Startup, the Deploys tab's webhook restarts the bot each time the workflow pushes a new jar. Deploy on push.

The token

String token = System.getenv("BOT_TOKEN");
JDA jda = JDABuilder.createDefault(token).build();

Some ready-made bots ask for their token in the console instead (JMusicBot does on its first start). Type it into the box at the bottom of the Console page; what you type there goes to the program's input.

Memory

The heap may use three quarters of your plan's memory (768 MB on Flurry); on its own, Java would only take a quarter. If the bot stops with java.lang.OutOfMemoryError, something is holding on to too much, or the bot needs a bigger plan. JDA's member and message caches are the usual suspects: turn off the cache flags and intents you do not use.

Stopping cleanly

Stop sends the program an interrupt, which runs Java's shutdown hooks. To let JDA close its connection to Discord properly, add one:

Runtime.getRuntime().addShutdownHook(new Thread(jda::shutdown));

When the jar will not start

• UnsupportedClassVersionError ... compiled by a more recent version: pick a newer Java under Startup.
• no main manifest attribute: the jar does not say which class to start. Set mainClass as above and rebuild.
• NoClassDefFoundError: net/dv8tion/jda/...: the jar was built without its dependencies. Use shadowJar or jar-with-dependencies.
• InvalidTokenException: the token is wrong or BOT_TOKEN is empty. Paste it into Startup and restart.

The console adds a [SnowServers] Hint: line for each of these.