Error encyclopedia

Common build, startup and runtime errors, what they mean and how to fix them.

BeginnerReference

Every error in this encyclopedia is a real message from the Java 25 compiler, Gradle or a Paper 26.3 server. Find yours, read what it means in plain English, and follow the fix.

How to read an error

Most errors have the same parts. Learning to spot them makes every error easier, even one you have never seen.

The parts of an exception report

The first line names the kind of problem. In Java that kind is called an exception, such as NullPointerException.
A list of lines starting with at is the stack trace: the chain of method calls that led to the problem, newest first. Look for the first line that names your own package and file, like JoinListener.java:42.
A line starting with Caused by: gives the deeper reason. The last Caused by is usually the real problem.
For compiler errors, the line has the file name, a colon and a line number: JoinListener.java:12: error: .... Start with the first error; later ones are often just follow-ups.
Gradle prints * What went wrong: before the useful part.

Find your error

Gradle and build errors (25): Problems when Gradle builds your project: dependencies, Java versions, the wrapper and build files.
Java compiler errors (43): What javac prints when your code has a mistake. Each one is a real message from the Java 25 compiler.
Plugin loading errors (19): Problems when the server starts and tries to load your plugin jar.
Runtime exceptions and server errors (36): Crashes inside your code while the plugin runs, and common server start problems.
Threading and lag errors (5): Using the game from the wrong thread, and slow code that makes the server lag.
YAML errors (7): Mistakes in plugin.yml, config.yml and other YAML files.
Config file errors (5): Reading and saving config files, and settings that are missing.
What players see (10): Messages and oddities that players report, and what causes them.
IntelliJ messages (7): Warnings and errors that appear in the editor or the Build window.

Gradle and build errors

Problems when Gradle builds your project: dependencies, Java versions, the wrapper and build files.

Gradle cannot find a dependency (the Paper repository is missing)

What you see

> Task :compileJava FAILEDFAILURE: Build failed with an exception.* What went wrong:Execution failed for task ':compileJava'.> Could not resolve all files for configuration ':compileClasspath'.   > Could not find io.papermc.paper:paper-api:26.3.build.142-beta.     Searched in the following locations:       - https://repo.maven.apache.org/maven2/io/papermc/paper/paper-api/26.3.build.142-beta/paper-api-26.3.build.142-beta.pom     If the artifact you are trying to retrieve can be found in the repository but without metadata in 'Maven POM' format, you need to adjust the 'metadataSources { ... }' of the repository declaration.     Required by:         project :* Try:> Run with --stacktrace option to get the stack trace.> Run with --info or --debug option to get more log output.> Run with --scan to get full insights from a Build Scan (powered by Develocity).> Get more help at https://help.gradle.org.BUILD FAILED in 3s1 actionable task: 1 executed

What it means. Gradle looked for a library your project needs (here the Paper API) and could not find it. The list under "Searched in the following locations" shows where it looked. If it only lists Maven Central, Gradle was never told about the Paper download site.

Likely causes

The repositories { } block in build.gradle.kts has no maven("https://repo.papermc.io/repository/maven-public/") line.
The repository line is there but in the wrong place, for example inside dependencies { }.
The library name or version has a typo.

How to fix it

Open build.gradle.kts and make the repositories block list both Maven Central and the Paper repository:
build.gradle.kts
```
1repositories {2    mavenCentral()3    maven("https://repo.papermc.io/repository/maven-public/")4}
```
Check that the line under dependencies reads compileOnly("io.papermc.paper:paper-api:$paperVersion") and that paperVersion in gradle.properties is 26.3.build.142-beta.
In IntelliJ press the elephant "Reload All Gradle Projects" button in the Gradle window, then build again.

Gradle cannot find that Paper API version (wrong version text)

What you see

> Task :compileJava FAILEDFAILURE: Build failed with an exception.* What went wrong:Execution failed for task ':compileJava'.> Could not resolve all files for configuration ':compileClasspath'.   > Could not find io.papermc.paper:paper-api:1.21.4-R0.1-SNAPSHOT.     Searched in the following locations:       - https://repo.maven.apache.org/maven2/io/papermc/paper/paper-api/1.21.4-R0.1-SNAPSHOT/maven-metadata.xml       - https://repo.papermc.io/repository/maven-public/io/papermc/paper/paper-api/1.21.4-R0.1-SNAPSHOT/maven-metadata.xml     Required by:         project :* Try:> Run with --stacktrace option to get the stack trace.> Run with --info or --debug option to get more log output.> Run with --scan to get full insights from a Build Scan (powered by Develocity).> Get more help at https://help.gradle.org.BUILD FAILED in 3s1 actionable task: 1 executed

What it means. Gradle searched the Paper repository too, but that exact version of the Paper API does not exist there. Old tutorials use versions like 1.21.4-R0.1-SNAPSHOT; Paper 26.3 uses a different style of version.

Likely causes

You copied a version number from an older tutorial.
A typo in the version, such as a missing build or an extra space.
The paperVersion value in gradle.properties is empty or was never read.

How to fix it

Set the version in gradle.properties to the one this guide uses:
gradle.properties
```
1minecraftVersion=26.32paperVersion=26.3.build.142-beta
```

Use that value in build.gradle.kts:

build.gradle.kts

1dependencies {2    compileOnly("io.papermc.paper:paper-api:$paperVersion")3}

To find the newest build, run update-paper-version.ps1 from the paper-templates folder, or look at the Paper downloads page.

Gradle cannot find a library (typo or missing repository)

What you see

> Task :compileJava FAILEDFAILURE: Build failed with an exception.* What went wrong:Execution failed for task ':compileJava'.> Could not resolve all files for configuration ':compileClasspath'.   > Could not find com.googlecode.json-simple:json-simpel:1.1.1.     Searched in the following locations:       - https://repo.maven.apache.org/maven2/com/googlecode/json-simple/json-simpel/1.1.1/json-simpel-1.1.1.pom       - https://repo.papermc.io/repository/maven-public/com/googlecode/json-simple/json-simpel/1.1.1/json-simpel-1.1.1.pom     Required by:         project :* Try:> Run with --stacktrace option to get the stack trace.> Run with --info or --debug option to get more log output.> Run with --scan to get full insights from a Build Scan (powered by Develocity).> Get more help at https://help.gradle.org.BUILD FAILED in 3s1 actionable task: 1 executed

What it means. Gradle looks libraries up by three words: group, name and version. It searched every repository you listed and none of them has a library with exactly those three words.

Likely causes

A typo in the group, name or version (as in json-simpel).
The library lives in a repository that is not listed in repositories { }.
The version was removed or never existed.

How to fix it

Copy the library's group:name:version text from its official page instead of typing it.
Compare it letter by letter with the line in build.gradle.kts.
If the library's page names a repository URL, add it with maven("https://...") inside repositories { }.
Reload Gradle in IntelliJ and build again.

Gradle cannot download (network problem)

What you see

> Task :compileJava FAILEDFAILURE: Build failed with an exception.* What went wrong:Execution failed for task ':compileJava'.> Could not resolve all files for configuration ':compileClasspath'.   > Could not resolve io.papermc.paper:paper-api:26.3.build.142-beta.     Required by:         project :      > Could not resolve io.papermc.paper:paper-api:26.3.build.142-beta.         > Could not get resource 'https://repo.papermc.io/repository/maven-public/io/papermc/paper/paper-api/26.3.build.142-beta/paper-api-26.3.build.142-beta.pom'.            > Could not GET 'https://repo.papermc.io/repository/maven-public/io/papermc/paper/paper-api/26.3.build.142-beta/paper-api-26.3.build.142-beta.pom'.               > repo.papermc.io: Temporary failure in name resolution* Try:> Run with --stacktrace option to get the stack trace.> Run with --info or --debug option to get more log output.> Run with --scan to get full insights from a Build Scan (powered by Develocity).> Get more help at https://help.gradle.org.BUILD FAILED in 3s1 actionable task: 1 executed

What it means. Gradle found the right address but could not reach the download server. The problem is your connection or the server, not your code.

Likely causes

No internet connection, or the connection dropped.
A VPN, proxy, school or office firewall, or antivirus is blocking Gradle.
The download site is having a short outage (status code 502, 503 or 504).

How to fix it

Open the address from the error in your browser. If the browser cannot open it either, fix your internet first.
Wait a minute and run the build again: outages are usually short.
Turn off the VPN for a moment, or check Windows Defender Firewall and your antivirus.
After one successful build the libraries are cached on your PC and later builds work offline.

Gradle is in offline mode and the library is not cached

What you see

> Task :compileJava FAILEDFAILURE: Build failed with an exception.* What went wrong:Execution failed for task ':compileJava'.> Could not resolve all files for configuration ':compileClasspath'.   > Could not resolve io.papermc.paper:paper-api:26.3.build.142-beta.     Required by:         project :      > No cached version of io.papermc.paper:paper-api:26.3.build.142-beta available for offline mode.* Try:> Run with --stacktrace option to get the stack trace.> Run with --info or --debug option to get more log output.> Run with --scan to get full insights from a Build Scan (powered by Develocity).> Get more help at https://help.gradle.org.BUILD FAILED in 3s1 actionable task: 1 executed

What it means. Gradle was told not to use the internet ("offline mode"), and the library you need has never been downloaded to this PC.

Likely causes

The "Toggle Offline Mode" button in IntelliJ's Gradle window is switched on.
--offline was added to the command.
org.gradle.offline=true is set in a gradle.properties file.

How to fix it

In IntelliJ open the Gradle tool window and click the "Toggle Offline Mode" icon so it is no longer highlighted.
Remove --offline from the run configuration or command.
Search gradle.properties (in the project and in C:\Users\<you>\.gradle) for offline and delete that line.
Build once while online so the library is saved.

Gradle cannot find a Java 25 toolchain

What you see

> Task :compileJava FAILEDFAILURE: Build failed with an exception.* What went wrong:Execution failed for task ':compileJava'.> Error while evaluating property 'javaCompiler' of task ':compileJava'.   > Failed to calculate the value of task ':compileJava' property 'javaCompiler'.      > Cannot find a Java installation on your machine (Windows 11 10.0 amd64) matching: Java 25 {languageVersion=25, vendor=any vendor, implementation=vendor-specific, nativeImageCapable=false}. Toolchain auto-provisioning is not enabled.         > No locally installed toolchains match and toolchain download repositories have not been configured.* Try:> Run with --stacktrace option to get the stack trace.> Run with --info or --debug option to get more log output.> Run with --scan to get full insights from a Build Scan (powered by Develocity).> Get more help at https://help.gradle.org.BUILD FAILED in 3s1 actionable task: 1 executed

What it means. Your build file asks for Java 25, but Gradle could not find Java 25 anywhere on this PC and is not allowed to download it.

Likely causes

Java 25 (JDK 25) is not installed.
It is installed, but Gradle cannot see it (installed in an unusual folder).
settings.gradle.kts is missing the foojay toolchain plugin, so Gradle may not download Java for you.

How to fix it

Install Eclipse Temurin JDK 25 from adoptium.net, then restart IntelliJ.

Make sure settings.gradle.kts contains the plugin that downloads missing Java versions:

build.gradle.kts

1plugins {2    id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0"3}4 5rootProject.name = "my-plugin"

In IntelliJ open File > Project Structure and check that the SDK is a JDK 25.
Run .\gradlew.bat -q javaToolchains to list the Java versions Gradle can see.

javac says "invalid source release: 25" (Java too old)

What you see

> Task :compileJava FAILEDerror: invalid source release: 25FAILURE: Build failed with an exception.* What went wrong:Execution failed for task ':compileJava'.> Compilation failed; see the compiler output below.  error: invalid source release: 25BUILD FAILED in 1s

What it means. The Java compiler that ran is older than Java 25, so it does not know the language level your build asks for.

Likely causes

Gradle or IntelliJ is using JDK 21 or older to compile.
The Gradle JVM setting in IntelliJ points to an old Java.
JAVA_HOME points to an old Java and no toolchain is configured.

How to fix it

Install JDK 25 (Eclipse Temurin) and restart IntelliJ.
In IntelliJ open File > Settings > Build, Execution, Deployment > Build Tools > Gradle and set Gradle JVM to your JDK 25.
Keep the toolchain block in build.gradle.kts so Gradle always picks Java 25:
build.gradle.kts
```
1java {2    toolchain.languageVersion = JavaLanguageVersion.of(25)3}
```
Open a new PowerShell window and run java -version. If it prints 21, your PATH or JAVA_HOME still points to the old one.

"Unsupported class file major version 69" (Gradle too old for Java 25)

What you see

FAILURE: Build failed with an exception.* What went wrong:Could not open cp_proj generic class cache for build file 'C:\Users\Steve\IdeaProjects\my-plugin\build.gradle' (C:\Users\Steve\.gradle\caches\7.6.1\scripts\8b2k4x1a6w).> BUG! exception in phase 'semantic analysis' in source unit '_BuildScript_' Unsupported class file major version 69* Try:> Run with --stacktrace option to get the stack trace.BUILD FAILED in 2s

What it means. Java versions have class file numbers: 65 is Java 21, 69 is Java 25. An old Gradle or tool is reading a Java 25 class and does not know that number yet.

Likely causes

The project uses an old Gradle version (for example 7.x or 8.x) while running on Java 25.
gradle/wrapper/gradle-wrapper.properties points to an old Gradle distribution.
An old build plugin (Kotlin, Shadow, paperweight) does not understand Java 25 yet.

How to fix it

Use the Gradle this guide uses. Edit gradle/wrapper/gradle-wrapper.properties:
gradle.properties
```
1distributionUrl=https\://services.gradle.org/distributions/gradle-9.8.0-bin.zip
```
Or run .\gradlew.bat wrapper --gradle-version 9.8.0 once, using a Java version your old Gradle understands.
Update plugins in build.gradle.kts to their newest versions.
Reload Gradle in IntelliJ and build again.

Gradle says Paper needs a newer Java than the build uses

What you see

> Task :compileJava FAILEDFAILURE: Build failed with an exception.* What went wrong:Execution failed for task ':compileJava'.> Could not resolve all files for configuration ':compileClasspath'.   > Could not resolve io.papermc.paper:paper-api:26.3.build.142-beta.     Required by:         project :      > No matching variant of io.papermc.paper:paper-api:26.3.build.142-beta was found. The consumer was configured to find a library for use during compile-time, compatible with Java 21, preferably in the form of class files, preferably optimized for standard JVMs, and its dependencies declared externally but:          - Variant 'apiElements' declares a library for use during compile-time, packaged as a jar, preferably optimized for standard JVMs, and its dependencies declared externally:              - Incompatible because this component declares a component, compatible with Java 25 and the consumer needed a component, compatible with Java 21* Try:> Run with --stacktrace option to get the stack trace.> Run with --info or --debug option to get more log output.> Run with --scan to get full insights from a Build Scan (powered by Develocity).> Get more help at https://help.gradle.org.BUILD FAILED in 3s1 actionable task: 1 executed

What it means. Paper 26.3 is built for Java 25. Gradle is compiling your plugin with an older Java, so it refuses to mix the two.

Likely causes

The java { toolchain ... } block is missing from build.gradle.kts.
Gradle runs on an older JDK and no toolchain asks for 25.

How to fix it

Add the toolchain so Gradle always compiles with Java 25:
build.gradle.kts
```
1java {2    toolchain.languageVersion = JavaLanguageVersion.of(25)3}
```
Make sure JDK 25 is installed. Gradle can find it itself, or download it when the foojay plugin is in settings.gradle.kts.
Reload Gradle and build again.

"gradlew is not recognized" in PowerShell or cmd

What you see

gradlew.bat : The term 'gradlew.bat' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.At line:1 char:1+ gradlew.bat build+ ~~~~~~~~~~~    + CategoryInfo          : ObjectNotFound: (gradlew.bat:String) [], CommandNotFoundException    + FullyQualifiedErrorId : CommandNotFoundExceptionSuggestion [2,General]: The command gradlew.bat was not found, but does exist in the current location. Windows PowerShell does not load commands from the current location by default. If you trust this command, instead type: ".\gradlew.bat".

What it means. PowerShell was asked to run gradlew.bat but did not find it. Either you are not in the project folder, or PowerShell needs .\ in front of programs in the current folder.

Likely causes

You typed gradlew.bat without .\ (PowerShell does not run programs from the current folder by name).
The terminal is open in the wrong folder, one without gradlew.bat.
You are using a Linux or Mac terminal and need ./gradlew instead.

How to fix it

In IntelliJ use the Terminal tool window: it opens in your project folder already.
Run the wrapper with .\ in front:
PowerShell
```
1.\gradlew.bat build
```
Type dir to see the files. You should see gradlew.bat, build.gradle.kts and settings.gradle.kts. If not, use cd to go into your project folder.

"Could not find or load main class org.gradle.wrapper.GradleWrapperMain"

What you see

Error: Could not find or load main class org.gradle.wrapper.GradleWrapperMainCaused by: java.lang.ClassNotFoundException: org.gradle.wrapper.GradleWrapperMain

What it means. The Gradle wrapper script is there, but the small helper jar it starts is missing, so Gradle cannot even begin.

Likely causes

gradle/wrapper/gradle-wrapper.jar was not copied (a zip was extracted without the gradle folder, or a .gitignore rule skipped *.jar).
The file is damaged.

How to fix it

Check that gradle\wrapper\gradle-wrapper.jar exists in your project.
Copy the whole gradle folder and gradlew.bat from a working project, such as one from the paper-templates folder.
If you have Gradle installed, run gradle wrapper --gradle-version 9.8.0 in the project folder to recreate the files.

Gradle wrapper cannot download Gradle itself

What you see

Downloading https://services.gradle.org/distributions/gradle-9.8.0-bin.zipException in thread "main" java.net.ConnectException: Connection timed out: connect	at java.base/sun.nio.ch.Net.connect0(Native Method)	at java.base/sun.nio.ch.Net.connect(Net.java:589)	at org.gradle.wrapper.Download.downloadInternal(Download.java:67)	at org.gradle.wrapper.Download.download(Download.java:48)	at org.gradle.wrapper.Install$1.call(Install.java:67)	at org.gradle.wrapper.GradleWrapperMain.main(GradleWrapperMain.java:67)

What it means. The first time you run gradlew.bat it downloads Gradle (about 130 MB). That download failed, so there is nothing to run yet.

Likely causes

No internet, VPN, proxy or firewall in the way.
The Gradle website was briefly unreachable.
A half-downloaded file is left in C:\Users\<you>\.gradle\wrapper\dists.

How to fix it

Check your connection and run the command again.
Open https://services.gradle.org/distributions/ in a browser to see if you can reach it.
Delete the folder named after the version in C:\Users\<you>\.gradle\wrapper\dists and run the wrapper again to start a fresh download.

"JAVA_HOME is not set and no 'java' command could be found"

What you see

ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.Please set the JAVA_HOME variable in your environment to match thelocation of your Java installation.

What it means. The Gradle wrapper needs a Java to start itself. It looked in JAVA_HOME and on your PATH and found nothing.

Likely causes

Java is not installed.
Java is installed, but the installer did not add it to PATH or set JAVA_HOME.
The terminal was opened before Java was installed and has not noticed it yet.

How to fix it

Install Eclipse Temurin JDK 25 from adoptium.net. In the installer, turn on "Set JAVA_HOME variable" and "Add to PATH".
Close the terminal and open a new one (or restart IntelliJ), then run java -version.
You can also run the build from IntelliJ's Gradle tool window, which uses the JDK chosen in the project settings.

"JAVA_HOME is set to an invalid directory"

What you see

ERROR: JAVA_HOME is set to an invalid directory: C:\Program Files\Java\jdk-17Please set the JAVA_HOME variable in your environment to match thelocation of your Java installation.

What it means. The JAVA_HOME setting points to a folder that does not exist (usually an old Java that you uninstalled).

Likely causes

You uninstalled or upgraded Java but JAVA_HOME still holds the old path.
A typo in the path, or a path that ends in \bin.

How to fix it

Open Windows Settings, search for "environment variables" and edit the system variable JAVA_HOME.
Set it to the JDK folder itself, for example C:\Program Files\Eclipse Adoptium\jdk-25.0.4.101-hotspot (not the bin folder inside it).
Open a new terminal and run echo $env:JAVA_HOME to check.

Unresolved reference in build.gradle.kts

What you see

FAILURE: Build failed with an exception.* Where:Build file 'C:\Users\Steve\IdeaProjects\my-plugin\build.gradle.kts' line: 18* What went wrong:Script compilation error:  Line 18:     compileOnlyy("io.papermc.paper:paper-api:$paperVersion")               ^ Unresolved reference: compileOnlyy1 error* Try:> Run with --stacktrace option to get the stack trace.> Run with --info or --debug option to get more log output.> Run with --scan to get full insights from a Build Scan (powered by Develocity).> Get more help at https://help.gradle.org.BUILD FAILED in 3s1 actionable task: 1 executed

What it means. Your build file is a Kotlin script. Kotlin found a name it does not know, so Gradle cannot read the file at all.

Likely causes

A typo in a Gradle word, such as compileOnlyy or repositorys.
A plugin that provides that word is missing from the plugins { } block.
A property such as paperVersion was never declared at the top of the file.

How to fix it

Open build.gradle.kts at the line number the message names and read the word carefully.
Compare with the build file in this guide or in the paper-templates folder.
If the unknown word belongs to a plugin (for example runServer), check that the plugin is listed in plugins { }.

Script compilation error in build.gradle.kts (missing bracket or quote)

What you see

FAILURE: Build failed with an exception.* Where:Build file 'C:\Users\Steve\IdeaProjects\my-plugin\build.gradle.kts' line: 14* What went wrong:Script compilation error:  Line 14:     maven("https://repo.papermc.io/repository/maven-public/"                                                                       ^ Expecting ')'1 error* Try:> Run with --stacktrace option to get the stack trace.> Run with --info or --debug option to get more log output.> Run with --scan to get full insights from a Build Scan (powered by Develocity).> Get more help at https://help.gradle.org.BUILD FAILED in 3s1 actionable task: 1 executed

What it means. Kotlin could not read your build file because a bracket, quote or word is missing or in the wrong place. The arrow ^ points to where it gave up, which is often just after the real mistake.

Likely causes

A missing closing ), } or quote.
An extra or missing comma.
Text pasted from a Groovy (build.gradle) tutorial into a Kotlin (build.gradle.kts) file. Groovy allows single quotes and no brackets; Kotlin does not.

How to fix it

Look at the line named in Line N: and the line above it.
Count the brackets: every ( needs a ) and every { a }.
Use double quotes for text: "like this".
In IntelliJ red underlines in the build file show the spot; fix those first.

Gradle plugin was not found

What you see

FAILURE: Build failed with an exception.* Where:Build file 'C:\Users\Steve\IdeaProjects\my-plugin\build.gradle.kts' line: 2* What went wrong:Plugin [id: 'xyz.jpenilla.run-paper', version: '3.1.1'] was not found in any of the following sources:- Gradle Core Plugins (plugin is not in 'org.gradle')- Included Builds (No included builds contain this plugin)- Plugin Repositories (could not resolve plugin artifact 'xyz.jpenilla.run-paper:xyz.jpenilla.run-paper.gradle.plugin:3.1.1')  Searched in the following repositories:    Gradle Central Plugin Repository* Try:> Run with --stacktrace option to get the stack trace.> Run with --info or --debug option to get more log output.> Run with --scan to get full insights from a Build Scan (powered by Develocity).> Get more help at https://help.gradle.org.BUILD FAILED in 3s1 actionable task: 1 executed

What it means. A plugin named in the plugins { } block does not exist in that version, or Gradle could not download it.

Likely causes

A typo in the plugin id or version number.
The plugin's version does not exist (it was never released).
No internet while Gradle tried to download it.

How to fix it

Use the plugin lines from this guide exactly:

build.gradle.kts

1plugins {2    java3    id("xyz.jpenilla.run-paper") version "3.1.0"4}

If you want a different version, look the plugin up on plugins.gradle.org and copy the id and version from there.
Check your connection and reload Gradle.

Gradle ran out of memory

What you see

Starting a Gradle Daemon, 1 busy and 1 incompatible Daemons could not be reused, use --status for details> Task :compileJava FAILEDExpiring Daemon because JVM heap space is exhaustedDaemon will be stopped at the end of the build after running out of JVM memoryFAILURE: Build failed with an exception.* What went wrong:Execution failed for task ':compileJava'.> Java heap space* Try:> Run with --stacktrace option to get the stack trace.BUILD FAILED in 41s

What it means. Gradle itself (not Minecraft) ran out of the memory it was allowed to use.

Likely causes

org.gradle.jvmargs in gradle.properties is too small or missing.
Many programs are open and Windows has little free memory.
A very large dependency or a build loop.

How to fix it

Give Gradle more memory in gradle.properties:
gradle.properties
```
1org.gradle.jvmargs=-Xmx2G -Dfile.encoding=UTF-8
```
Run .\gradlew.bat --stop to stop old Gradle processes, then build again.
Close big programs (browsers with many tabs, the game) and try again.

Gradle says a task was not found

What you see

FAILURE: Build failed with an exception.* What went wrong:Task 'runServr' not found in root project 'my-plugin'. Some candidates are: 'runServer'.* Try:> Run gradlew tasks to get a list of available tasks.> For more on name expansion, please refer to https://docs.gradle.org/9.8.0/userguide/command_line_interface.html#sec:name_abbreviation in the Gradle documentation.> Run with --stacktrace option to get the stack trace.BUILD FAILED in 1s

What it means. You asked Gradle to run a task with a name it does not have. Tasks are the jobs Gradle can do, such as build or runServer.

Likely causes

A typo in the task name (Gradle often suggests the right one under "Some candidates").
The plugin that adds the task (for example run-paper adds runServer) is not applied.
You are in a folder that is not your project.

How to fix it

Use the candidate Gradle suggests, or run .\gradlew.bat tasks to see every task.
For runServer check that this line is in the plugins block:
build.gradle.kts
```
1id("xyz.jpenilla.run-paper") version "3.1.0"
```
Check that the terminal is open in the project folder.

Gradle says the folder does not contain a Gradle build

What you see

FAILURE: Build failed with an exception.* What went wrong:Directory 'C:\Users\Steve\Documents' does not contain a Gradle build.A Gradle build should contain a 'settings.gradle' or 'settings.gradle.kts' file in its root directory. It may also contain a 'build.gradle' or 'build.gradle.kts' file.To create a new Gradle build in this directory run 'gradlew init'For more detail on the 'init' task, see https://docs.gradle.org/9.8.0/userguide/build_init_plugins.html

What it means. Gradle looked in the current folder for settings.gradle.kts and did not find it. You are in the wrong folder, or you opened a folder one level too high or too low.

Likely causes

The terminal is not in the project folder.
In IntelliJ you opened a parent folder instead of the project folder.
settings.gradle.kts was deleted or renamed.

How to fix it

Use cd to move into the folder that holds settings.gradle.kts.
In IntelliJ choose File > Open and pick the folder that contains build.gradle.kts directly.
Make sure settings.gradle.kts exists and contains rootProject.name = "my-plugin".

Gradle: "Compilation failed; see the compiler output below"

What you see

> Task :compileJava FAILEDFAILURE: Build failed with an exception.* What went wrong:Execution failed for task ':compileJava'.> Compilation failed; see the compiler output below.BUILD FAILED in 2s1 actionable task: 1 executed

What it means. This is only the wrapper message: your Java code has mistakes. The real reasons are the lines that start with a file name and error:, usually above this message.

Likely causes

One or more compile errors in your .java files.
A missing import or a missing dependency.

How to fix it

Scroll up in the Run window until you find lines like JoinListener.java:12: error: ... and read those.
Paste the whole output into the Error Doctor: it lists every error with its file and line.
Fix the first error first; later errors are often caused by it.

Gradle cannot delete a file in the build folder

What you see

> Task :clean FAILEDFAILURE: Build failed with an exception.* What went wrong:Execution failed for task ':clean'.> Unable to delete directory 'C:\Users\Steve\IdeaProjects\my-plugin\build'    Failed to delete some children. This might happen because a process has files open or has its working directory set in the target directory.    - C:\Users\Steve\IdeaProjects\my-plugin\build\libs\my-plugin-1.0.0.jar* Try:> Run with --stacktrace option to get the stack trace.BUILD FAILED in 1s

What it means. Windows will not let Gradle delete a file that another program is using. Most often the test server is running and has your plugin jar open.

Likely causes

A Minecraft or Paper server that loaded your plugin jar is still running.
File Explorer or an antivirus scan has the folder open.
An old Gradle or Java process is still running.

How to fix it

Stop the server (type stop in its console, or press the red square in IntelliJ).
Close File Explorer windows that show the build folder.
Run .\gradlew.bat --stop, then build again.
If it still fails, restart IntelliJ.

Gradle property not found (paperVersion and similar)

What you see

FAILURE: Build failed with an exception.* Where:Build file 'C:\Users\Steve\IdeaProjects\my-plugin\build.gradle.kts' line: 6* What went wrong:Cannot get property 'paperVersion' on extra properties extension as it does not exist* Try:> Run with --stacktrace option to get the stack trace.BUILD FAILED in 1s

What it means. The build file reads a value (like paperVersion) that should live in gradle.properties, but Gradle cannot find it there.

Likely causes

gradle.properties is missing or in the wrong folder (it belongs next to build.gradle.kts).
The name in gradle.properties is spelled differently, or the file has a typo before the =.
The file was saved as gradle.properties.txt.

How to fix it

Create or fix gradle.properties in the project root:

gradle.properties

1group=com.example2version=1.0.03minecraftVersion=26.34paperVersion=26.3.build.142-beta

In File Explorer turn on "File name extensions" and check the file is not named gradle.properties.txt.
Reload Gradle in IntelliJ.

Gradle waits for a lock (another Gradle is running)

What you see

FAILURE: Build failed with an exception.* What went wrong:Timeout waiting to lock journal cache (C:\Users\Steve\.gradle\caches\journal-1). It is currently in use by another Gradle instance.Owner PID: 14212Our PID: 20844Owner Operation: Our operation: Lock file: C:\Users\Steve\.gradle\caches\journal-1\journal-1.lockBUILD FAILED in 1m 3s

What it means. Two Gradle processes tried to use the same cache folder at once, and one had to wait too long.

Likely causes

A second build started from IntelliJ or a terminal while another still ran.
A Gradle process crashed and left its lock behind.

How to fix it

Wait for the other build to finish, then try again.
Run .\gradlew.bat --stop to stop all Gradle processes.
If it keeps happening, restart your PC or end the Java processes in Task Manager.

Read more: Build, install and test

Gradle: PKIX path building failed (certificate problem)

What you see

> Could not resolve all files for configuration ':compileClasspath'.   > Could not resolve io.papermc.paper:paper-api:26.3.build.142-beta.      > Could not get resource 'https://repo.papermc.io/repository/maven-public/io/papermc/paper/paper-api/26.3.build.142-beta/paper-api-26.3.build.142-beta.pom'.         > Could not GET 'https://repo.papermc.io/repository/maven-public/io/papermc/paper/paper-api/26.3.build.142-beta/paper-api-26.3.build.142-beta.pom'.            > PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

What it means. Java did not trust the website's security certificate. This usually means something between you and the internet (antivirus, a school or work network) is inspecting the connection.

Likely causes

Antivirus "web shield" or HTTPS scanning is on.
A school or company network with its own certificate.
A very old Java that does not know new certificates.

How to fix it

Temporarily turn off HTTPS scanning in your antivirus and try again.
Try another network (for example a phone hotspot) to confirm the network is the cause.
Use an up-to-date JDK 25.
On a work network ask the administrator how to add the company certificate to Java.

Java compiler errors

What javac prints when your code has a mistake. Each one is a real message from the Java 25 compiler.

cannot find symbol: class (missing import or typo in a type name)

What you see

> Task :compileJava FAILEDC:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:10: error: cannot find symbol        Player player = event.getPlayer();        ^  symbol:   class Player  location: class JoinListener1 errorFAILURE: Build failed with an exception.* What went wrong:Execution failed for task ':compileJava'.> Compilation failed; see the compiler output below.  C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:10: error: cannot find symbol          Player player = event.getPlayer();          ^    symbol:   class Player    location: class JoinListener  1 error* Try:> Run with --info option to get more log output.> Run with --scan to get full insights from a Build Scan (powered by Develocity).BUILD FAILED in 2s1 actionable task: 1 executed

What it means. The compiler met a class name (such as Player) that it has never heard of. Java only knows the names in your own file, in java.lang, and in the classes you import.

Likely causes

The import line for that class is missing.
The class name is misspelled or has the wrong capital letters (player instead of Player).
The library that contains the class is not in build.gradle.kts.

How to fix it

In IntelliJ click the red name and press Alt+Enter, then choose Import class.
Or add the import yourself, at the top under the package line:
Java
```
1import org.bukkit.entity.Player;
```
Check the spelling and the capital letters.
If IntelliJ offers no import, the library is missing: add it under dependencies and reload Gradle.

cannot find symbol: variable (typo or out of scope)

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:12: error: cannot find symbol        playr.sendRichMessage("<green>Welcome!");        ^  symbol:   variable playr  location: class JoinListener1 error

What it means. You used a name as if it were a variable, but nothing with that name exists at that spot.

Likely causes

A typo (playr instead of player).
The variable was created inside other braces { } (an if, a loop or another method) and does not exist outside them.
You forgot to create the variable at all.
You wanted a class name, but its import is missing and Java assumed a variable.

How to fix it

Compare the spelling with the line where the variable is created. Java cares about every letter and every capital.
Check where the variable was created: you can only use it inside the same pair of braces or deeper.

If the variable is needed in more than one place, create it earlier:

Java

1Player player = event.getPlayer();2if (player.isOp()) {3    player.sendRichMessage("<gold>Hello operator!");4}

cannot find symbol: method (typo, wrong type or wrong arguments)

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:12: error: cannot find symbol        player.sendMesage("Welcome!");              ^  symbol:   method sendMesage(String)  location: variable player of type Player1 error

What it means. You called a method (an action) that does not exist on that kind of object. The location line tells you which object and type Java checked.

Likely causes

A typo in the method name (sendMesage).
The method exists on a different class, or only in an older version of Paper.
The argument types do not match any version of the method (the symbol line shows the types you passed).
You called it on the wrong variable.

How to fix it

Fix the spelling. IntelliJ's autocomplete (Ctrl+Space) lists the real names after you type a dot.
Look up the class in the API map or the Javadoc to see which methods it really has.
Check the arguments: the symbol line shows method sendMesage(String), the types you passed.
Use the Names Lookup tool if you remember an old name from an old tutorial.

package does not exist (missing library or typo in an import)

What you see

> Task :compileJava FAILEDC:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\ShopListener.java:3: error: package net.milkbowl.vault.economy does not existimport net.milkbowl.vault.economy.Economy;                                 ^C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\ShopListener.java:7: error: cannot find symbol    private Economy economy;            ^  symbol:   class Economy  location: class ShopListener2 errorsFAILURE: Build failed with an exception.* What went wrong:Execution failed for task ':compileJava'.> Compilation failed; see the compiler output below.  C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\ShopListener.java:3: error: package net.milkbowl.vault.economy does not exist  import net.milkbowl.vault.economy.Economy;                                   ^  C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\ShopListener.java:7: error: cannot find symbol      private Economy economy;              ^    symbol:   class Economy    location: class ShopListener  2 errors* Try:> Run with --info option to get more log output.> Run with --scan to get full insights from a Build Scan (powered by Develocity).BUILD FAILED in 2s1 actionable task: 1 executed

What it means. An import line names a folder of classes (a package) that Java cannot find. Usually the library that contains it is not part of your project.

Likely causes

The library (for example Vault) is not in build.gradle.kts, so its classes are not available when compiling.
A typo in the import (org.bucket instead of org.bukkit).
An old import from a tutorial for a different Minecraft version.

How to fix it

Fix the spelling of the import first.
For another plugin's classes, add it as a compileOnly dependency and its repository, then reload Gradle.
For Paper classes, use the import IntelliJ suggests with Alt+Enter.
Remember to also list the other plugin under depend or softdepend in plugin.yml.

incompatible types: X cannot be converted to Y

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\CoinsCommand.java:5: error: incompatible types: String cannot be converted to int        int amount = "50";                     ^1 error

What it means. You tried to put one kind of value into a place that holds another kind, like text into a number box. Java will not guess how to convert it.

Likely causes

Text (a String) in quotes assigned to a number variable.
A number used where text is needed.
A method that returns one type, stored in a variable of another type.

How to fix it

Remove the quotes if you meant a number: int amount = 50;.
To turn text into a number use Integer.parseInt:
Java
```
1int amount = Integer.parseInt("50");
```
To turn a number into text add it to a string:
Java
```
1String text = "Coins: " + amount;
```
Check what the method returns: hover over it in IntelliJ.

Read more: Variables and types, Working with text

incompatible types: Entity cannot be converted to Player (needs a cast)

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\DamageListener.java:11: error: incompatible types: Entity cannot be converted to Player        Player victim = event.getEntity();                                       ^1 error

What it means. The method gives you something general (an Entity) and you stored it in something more specific (a Player). Every player is an entity, but not every entity is a player, so Java wants you to check first.

Likely causes

Events such as EntityDamageEvent return an Entity or CommandSender, not a Player.
You forgot to check instanceof before converting.

How to fix it

Check the type with instanceof and use the pattern variable:

Java

1if (event.getEntity() instanceof Player victim) {2    victim.sendRichMessage("<red>Ouch!");3}

For commands, a sender can be the console, so check it before you cast:

Java

1if (!(sender instanceof Player player)) {2    sender.sendRichMessage("<red>Only players can use this.");3    return true;4}

possible lossy conversion from double to int

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:12: error: incompatible types: possible lossy conversion from double to int        int half = player.getHealth() / 2;                                      ^1 error

What it means. You put a number with a decimal part into a whole-number box. Java stops you because the part after the dot would be thrown away without warning.

Likely causes

Methods like getHealth() return a double, and you stored it in an int.
Math such as / 2.0 makes the result a double.

How to fix it

Use a double variable if you want to keep the decimals:
Java
```
1double health = player.getHealth();
```
Or round on purpose with a cast, if you really want a whole number:
Java
```
1int half = (int) (player.getHealth() / 2);
```

Or round to the nearest whole number:

Java

1int rounded = (int) Math.round(player.getHealth());

Read more: Operators and math, Variables and types

missing return statement

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\CoinsCommand.java:8: error: missing return statement    }    ^1 error

What it means. A method promised to give back a value (it has a type like int instead of void) but there is a way through it that ends without a return.

Likely causes

An if returns a value but there is no return for the case where the if is false.
A loop or switch where some paths do not return.

How to fix it

Make sure every path returns something, for example by adding a final return:

Java

1public int bonusFor(boolean vip) {2    if (vip) {3        return 100;4    }5    return 0;6}

Or change the return type to void if the method should not return anything.

';' expected (missing semicolon)

What you see

> Task :compileJava FAILEDC:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:12: error: ';' expected        player.sendRichMessage("<green>Welcome!")                                                 ^1 errorFAILURE: Build failed with an exception.* What went wrong:Execution failed for task ':compileJava'.> Compilation failed; see the compiler output below.  C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:12: error: ';' expected          player.sendRichMessage("<green>Welcome!")                                                   ^  1 error* Try:> Run with --info option to get more log output.> Run with --scan to get full insights from a Build Scan (powered by Develocity).BUILD FAILED in 2s1 actionable task: 1 executed

What it means. Every simple instruction in Java ends with a semicolon, like a period ends a sentence. The compiler found the end of an instruction without one.

Likely causes

A forgotten ; at the end of the line that the arrow points to, or the line before.
A line that was split in two by accident.

How to fix it

Add the semicolon at the end of the statement:
Java
```
1player.sendRichMessage("<green>Welcome!");
```
Look at the line shown in the error. The caret ^ points just after the place where the semicolon belongs.
Do not add semicolons after if (...), for (...) or after a method header before its {.

Read more: How code reads

')' expected or ')' or ',' expected (missing closing bracket)

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:12: error: ')' or ',' expected        player.sendRichMessage("<green>Welcome!";                                                ^1 error

What it means. Brackets come in pairs: every ( needs a ). The compiler reached a place where a closing bracket (or a comma between arguments) had to be and found something else.

Likely causes

The closing ) is missing before the semicolon.
Brackets are in the wrong order, or a comma is missing between two arguments.
A quote was not closed.

How to fix it

Close the bracket before the semicolon:
Java
```
1player.sendRichMessage("<green>Welcome!");
```
Count the ( and ) on the line: the numbers must match.
In IntelliJ put the cursor next to a bracket: its partner is highlighted.

Read more: How code reads, Methods: reusable actions

class X is public, should be declared in a file named X.java

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:3: error: class JoinListner is public, should be declared in a file named JoinListner.javapublic class JoinListner {       ^1 error

What it means. Java insists that a public class lives in a file with exactly the same name. The class name and the file name must match letter for letter, including capitals.

Likely causes

You renamed the class but not the file (or the other way round).
A typo in one of them (JoinListner).
You copied a file and forgot to rename the class inside.

How to fix it

In IntelliJ rename the class with Shift+F6 while the cursor is on its name. It renames the file too.
Check that the file is called exactly JoinListener.java when the class is JoinListener.

unreported exception X; must be caught or declared to be thrown

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:12: error: unreported exception InterruptedException; must be caught or declared to be thrown        Thread.sleep(1000);                    ^1 error

What it means. The code you called can fail in a way Java wants you to plan for (a "checked exception", like a file that cannot be read). You must either handle it or pass it on.

Likely causes

Calling Thread.sleep, reading or writing files, or network code without try/catch.

How to fix it

Handle it with try/catch:

Java

1try {2    Files.readString(path);3} catch (IOException exception) {4    getLogger().warning("Could not read the file: " + exception.getMessage());5}

Or add throws IOException to your method, if the caller can deal with it. Event handlers usually cannot, so use try/catch there.
Never use Thread.sleep in plugin code: it freezes the whole server. Use the scheduler instead.

method does not override or implement a method from a supertype

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\MyPlugin.java:6: error: method does not override or implement a method from a supertype    @Override    ^1 error

What it means. You wrote @Override, which says "this replaces a method from the parent class". Java looked and the parent has no method with that exact name and parameters.

Likely causes

A typo in the method name (onEnabel).
Wrong parameter types or a different number of parameters.
The method existed in an older version of the API but was removed.

How to fix it

Fix the spelling: the real name is onEnable.
Let IntelliJ write the method for you: Ctrl+O lists methods you can override.
Compare the parameters with the Javadoc of the class.

non-static method cannot be referenced from a static context

What you see

Main.java:9: error: non-static method showCoins() cannot be referenced from a static context        showCoins();        ^1 error

What it means. static methods belong to the class itself, while normal methods belong to one object made from the class. A static method has no object, so it cannot call a normal method directly.

Likely causes

Calling a normal method from main or another static method.

How to fix it

Make an object first, then call the method on it:

Java

1public static void main(String[] args) {2    Main main = new Main();3    main.showCoins();4}

Or make the method static too, if it does not need any data of an object.
In a plugin, avoid static for things that belong to your plugin: pass the plugin object to your classes instead.

non-static variable cannot be referenced from a static context

What you see

Main.java:5: error: non-static variable coins cannot be referenced from a static context        coins = coins + 1;        ^Main.java:5: error: non-static variable coins cannot be referenced from a static context        coins = coins + 1;                ^Main.java:6: error: non-static variable coins cannot be referenced from a static context        IO.println(coins);                   ^3 errors

What it means. A field (a variable inside a class) belongs to an object. main is static, so there is no object yet, and Java does not know whose coins you mean.

Likely causes

Using an instance field from static void main.

How to fix it

Create an object and use the field through it:

Java

1Main main = new Main();2main.coins = main.coins + 1;

Or declare the field static if only one copy is needed for the whole program.

variable might not have been initialized

What you see

Main.java:6: error: variable name might not have been initialized    IO.println("Hello " + name);                          ^1 error

What it means. You created a variable without a value and then used it. Java checked every path and found one where the variable never gets a value.

Likely causes

The variable is only assigned inside an if or loop that may not run.

How to fix it

Give the variable a starting value:

Java

1String name = "friend";2if (args.length > 0) {3    name = args[0];4}5IO.println("Hello " + name);

Or make sure every branch of the if and else assigns it.

unreachable statement

What you see

Main.java:4: error: unreachable statement    IO.println("This never runs");    ^1 error

What it means. There is code after a return, break, continue or throw. The method leaves before it can get there, so that line could never run.

Likely causes

A return in the middle of a method.
An endless loop while (true) without a break, followed by more code.

How to fix it

Delete the code after the return, or move it before it.
If you wanted the code to run only sometimes, wrap the return in an if.

Deprecation warning (or deprecation turned into an error)

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:12: warning: [deprecation] setDisplayName(@org.jspecify.annotations.Nullable String) in Player has been deprecated        player.setDisplayName("Hero " + player.getName());              ^1 warning

What it means. The method you used still works, but the Paper team marked it as old and wants you to use a newer replacement. If your build turns warnings into errors (-Werror), the build fails.

Likely causes

You copied code from an older tutorial (for example setDisplayName(String) or ChatColor).
Paper replaced the method with a Component-based version.

How to fix it

Read the warning: it names the method. Search the Javadoc for its replacement.

Example: use a Component for names instead of a String:

Java

1player.displayName(MiniMessage.miniMessage().deserialize("<gold>Hero"));

Many chapters in this guide show the modern way for each old method.

illegal start of expression

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:12: error: illegal start of expression        public int bonus = 5;        ^C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:13: error: <identifier> expected        player.sendRichMessage("Bonus " + bonus);                              ^C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:13: error: illegal start of type        player.sendRichMessage("Bonus " + bonus);                               ^C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:15: error: class, interface, enum, or record expected}^4 errors

What it means. The compiler found something where it expected the start of a normal instruction. It usually means a bracket is missing earlier or a word is in a place where it is not allowed, such as public inside a method.

Likely causes

A public or private word on a variable inside a method (only fields in a class use them).
A missing } or ) on an earlier line that confuses everything after it.
A method written inside another method.

How to fix it

Delete public, private and static from variables inside methods.
Check the brackets above the line, and fix the first error in the list first: the later ones are often just follow-ups.
In IntelliJ use Ctrl+Alt+L to reformat: if the indentation looks wrong, a bracket is missing.

Read more: How code reads, Methods: reusable actions

class, interface, enum, or record expected (extra closing brace)

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:15: error: class, interface, enum, or record expected}^1 error

What it means. Java found code outside any class. It almost always means there is one } too many, so the class ended earlier than you meant.

Likely causes

An extra } before the end of the file.
A method written below the final } of the class.

How to fix it

Scroll to the error line and look at the } there: delete it if it has no partner.
In IntelliJ press Ctrl+Alt+L. Code that does not line up shows where the brackets went wrong.
Move code that sits below the last } back into the class.

Read more: How code reads, Classes and objects

reached end of file while parsing (missing closing brace)

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:12: error: reached end of file while parsing    }     ^1 error

What it means. The file ended while Java still expected a }. A bracket that was opened was never closed.

Likely causes

A missing } at the end of a method or class.
A deleted line that contained a closing brace.

How to fix it

Count the { and } in the file: they must be equal.
Reformat with Ctrl+Alt+L and look for the place where the indentation stops making sense.
Add the missing } at the end.

Read more: How code reads

variable is already defined in method

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:12: error: variable player is already defined in method onJoin(PlayerJoinEvent)        Player player = event.getPlayer();               ^1 error

What it means. You created two variables with the same name in the same method. Each name can be created only once in the same scope.

Likely causes

Copy and paste that kept the old Player player = ... line.
A loop variable with the same name as another variable.

How to fix it

Delete the second creation and just reuse the variable: player = event.getPlayer();.
Or give the second variable another name.

Read more: Variables and types

method cannot be applied to given types

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:12: error: method heal in class JoinListener cannot be applied to given types;        heal(player);        ^  required: Player,double  found:    Player  reason: actual and formal argument lists differ in length1 error

What it means. The method exists, but you called it with the wrong number or kinds of arguments. The error lists what it required and what you found.

Likely causes

A missing argument or an extra one.
Arguments in the wrong order.
A String where a number is needed.

How to fix it

Compare the required line with the found line. They must match in count and order.
Fix the call so it matches the method:
Java
```
1heal(player, 5.0);
```
Hover over the method in IntelliJ and press Ctrl+P inside the brackets to see the parameters.

Read more: Methods: reusable actions

not a statement

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:12: error: not a statement        player.getName;              ^1 error

What it means. A line of code has to do something, like call a method or assign a value. This line only names something and then stops.

Likely causes

A method call missing its (): player.getName;.
A stray word or a missing operator.

How to fix it

Add the brackets to call the method:
Java
```
1String name = player.getName();
```
If you did not mean to write the line, delete it.

Read more: Methods: reusable actions, How code reads

bad operand types for binary operator

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:12: error: bad operand types for binary operator '=='        if (player.getName() == 5) {                             ^  first type:  String  second type: int1 error

What it means. You compared or combined two values of types that do not go together, such as text and a number.

Likely causes

Comparing a String with a number using ==.
Using && on numbers instead of true/false values.

How to fix it

Compare text with text, and use equals for text:

Java

1if (player.getName().equals("Steve")) {2    player.sendRichMessage("Hello Steve!");3}

Convert text to a number first if you need a number comparison: Integer.parseInt(text).

Read more: Operators and math, Working with text

cannot assign a value to final variable

What you see

Main.java:3: error: cannot assign a value to final variable maxPlayers    maxPlayers = 30;    ^1 error

What it means. A variable marked final is a constant: it gets one value and can never change.

Likely causes

You want to change a value you declared with final.

How to fix it

Remove final if the value needs to change.
Or use a new variable for the new value.

Read more: Variables and types

X is abstract; cannot be instantiated

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\Setup.java:7: error: Listener is abstract; cannot be instantiated        Listener listener = new Listener();                            ^1 error

What it means. You tried to create an object with new from something that is only a description (an interface or abstract class). It says what an object can do, but not how.

Likely causes

new Listener(), new Player() or new Entity(): those are interfaces.

How to fix it

Make your own class that implements the interface and create that:
Java
```
1public class MyListener implements Listener {2}
```
To get a real Player, take it from an event or from Bukkit.getPlayer(...); you never create one with new.

class is not abstract and does not override abstract method

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\HealCommand.java:5: error: HealCommand is not abstract and does not override abstract method onCommand(@org.jetbrains.annotations.NotNull CommandSender,@org.jetbrains.annotations.NotNull Command,@org.jetbrains.annotations.NotNull String,@org.jetbrains.annotations.NotNull String @org.jetbrains.annotations.NotNull []) in CommandExecutorpublic class HealCommand implements CommandExecutor {       ^1 error

What it means. Your class says it follows an interface (implements CommandExecutor), but it does not contain all the methods that interface demands.

Likely causes

You forgot to write the required method.
The method is there but its parameters differ from the interface.

How to fix it

Click the red class name and press Alt+Enter, then Implement methods.

Add the method named in the error:

Java

1@Override2public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {3    return true;4}

int cannot be dereferenced

What you see

Main.java:3: error: int cannot be dereferenced    String text = level.toString();                       ^1 error

What it means. A dot after a value means "use a method of this object". Basic number types such as int are not objects and have no methods.

Likely causes

Calling .toString() or .equals() on an int, double or boolean.

How to fix it

Convert the number with String.valueOf or add it to text:
Java
```
1String text = String.valueOf(level);
```
Compare numbers with ==, not .equals(...).

Read more: Variables and types, Working with text

incompatible types: unexpected return value

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\HealCommand.java:5: error: incompatible types: unexpected return value        return 5;               ^1 error

What it means. The method is declared void, which means "gives back nothing", but it contains return 5;.

Likely causes

The return type should be int (or another type) instead of void.

How to fix it

Change the return type to the type you return:
Java
```
1public int healAmount() {2    return 5;3}
```
Or remove the value: use a plain return; in a void method.

Read more: Methods: reusable actions

'else' without 'if'

What you see

Main.java:6: error: 'else' without 'if'    else    ^1 error

What it means. An else has to follow directly after the if it belongs to. Without braces, an if only covers one line, so the second line ended the if early.

Likely causes

Several lines under an if without { }.
A semicolon right after if (...).

How to fix it

Always use braces:

Java

1if (score > 5) {2    IO.println("High");3    IO.println("Nice");4} else {5    IO.println("Low");6}

unclosed string literal

What you see

Main.java:2: error: unclosed string literal    IO.println("Hello world);               ^1 error

What it means. Text in Java starts and ends with a double quote. The compiler found the opening quote but no closing one on the same line.

Likely causes

A missing " at the end of the text.
A quote inside the text that was not escaped.

How to fix it

Close the quote:
Java
```
1IO.println("Hello world");
```
To put a quote inside text, put a backslash before it:
Java
```
1player.sendRichMessage("She said \"hi\"");
```

Read more: Working with text

attempting to assign weaker access privileges

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\MyPlugin.java:7: error: onEnable() in MyPlugin cannot implement onEnable() in Plugin    void onEnable() {         ^  attempting to assign weaker access privileges; was public1 error

What it means. You replaced a method that is public in the parent class, but you wrote yours without public. A replacement may never be less open than the original.

Likely causes

Forgetting the word public before void onEnable().

How to fix it

Add public:

Java

1@Override2public void onEnable() {3    getLogger().info("Hello!");4}

has private access

What you see

Main.java:8: error: coins has private access in Wallet        IO.println(wallet.coins);                         ^1 error

What it means. That variable or method was marked private, which means only code inside its own class may use it.

Likely causes

You tried to read or change another class's private field.

How to fix it

Ask the class to share the value with a method (a "getter"):
Java
```
1public int getCoins() {2    return coins;3}
```
Then call wallet.getCoins() instead of wallet.coins.

invalid method declaration; return type required

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\CoinsCommand.java:4: error: invalid method declaration; return type required    public giveCoins() {           ^1 error

What it means. Every method needs to say what it gives back (void, int, String...). Only constructors skip it, and their name must match the class.

Likely causes

A missing return type, such as public giveCoins().
A constructor whose name does not match the class name.
A line of code placed directly inside the class instead of inside a method.

How to fix it

Add the return type:
Java
```
1public void giveCoins() {2}
```
Check that code lines (like getLogger().info(...)) are inside a method.

<identifier> expected (code outside a method)

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:4: error: <identifier> expected    System.out.println("Loaded");                      ^C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:4: error: illegal start of type    System.out.println("Loaded");                       ^2 errors

What it means. Instructions such as getLogger().info(...) must live inside a method. Directly inside a class Java only expects field and method declarations.

Likely causes

A statement was written directly in the class body.
A missing method header above the line.

How to fix it

Move the line into a method, for example onEnable:

Java

1@Override2public void onEnable() {3    getLogger().info("Loaded");4}

no suitable method found for method(argument)

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:12: error: no suitable method found for sendMessage(int)        player.sendMessage(5);              ^    method Audience.sendMessage(ComponentLike) is not applicable      (argument mismatch; int cannot be converted to ComponentLike)    method CommandSender.sendMessage(@org.jetbrains.annotations.NotNull String) is not applicable      (argument mismatch; int cannot be converted to String)    method CommandSender.sendMessage(@org.jetbrains.annotations.NotNull String...) is not applicable      (varargs mismatch; int cannot be converted to String)    method CommandSender.sendMessage(@org.jetbrains.annotations.Nullable UUID,@org.jetbrains.annotations.NotNull String...) is not applicable      (argument mismatch; int cannot be converted to UUID)    method CommandSender.sendMessage(@org.jetbrains.annotations.NotNull Component) is not applicable      (argument mismatch; int cannot be converted to Component)    method Player.sendMessage(BaseComponent) is not applicable

What it means. The method exists in several versions (overloads) and none of them accepts the argument you gave. The indented list shows every version and why it does not fit.

Likely causes

A number or other type passed where text or a Component is needed.
Passing a Component to a method that wants String (or the other way round).

How to fix it

Look at the list: every method X is not applicable line shows which type it needed.

Turn the number into text, or use sendRichMessage:

Java

1player.sendRichMessage("<green>You have " + coins + " coins");

local variables referenced from a lambda must be final or effectively final

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\CountdownTask.java:13: error: local variables referenced from a lambda expression must be final or effectively final            secondsLeft--;            ^C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\CountdownTask.java:14: error: local variables referenced from a lambda expression must be final or effectively final            plugin.getLogger().info("Seconds left: " + secondsLeft);                                                       ^2 errors

What it means. A lambda (the short task -> { ... } code you give to the scheduler) runs later, and it only gets a copy of local variables. So Java does not allow the variable to change.

Likely causes

A counter such as secondsLeft-- inside a scheduler task.

How to fix it

Keep the changing number in a field of your class (or an AtomicInteger), not in a local variable:

Java

1private int secondsLeft = 10;2 3public void start() {4    plugin.getServer().getScheduler().runTaskTimer(plugin, task -> {5        secondsLeft--;6    }, 0L, 20L);7}

Or use AtomicInteger counter = new AtomicInteger(10); and call counter.decrementAndGet() inside the lambda.

unexpected type; required: reference, found: int

What you see

Main.java:5: error: unexpected type    List<int> scores = new ArrayList<>();         ^  required: reference  found:    int1 error

What it means. Lists, sets and maps can only hold objects, and int is a basic value. Java has an object twin for each basic type: Integer, Double, Boolean, Long.

Likely causes

Writing List<int> or Map<String, double>.

How to fix it

Use the object type between the angle brackets:
Java
```
1List<Integer> scores = new ArrayList<>();
```

Read more: Lists, sets and maps, Variables and types

array required, but List found

What you see

Main.java:5: error: array required, but List<String> found    IO.println(homes[0]);                    ^1 error

What it means. Square brackets like homes[0] only work on arrays. A List has to be read with .get(0).

Likely causes

Using array syntax on a List, or the other way round.

How to fix it

Use get for lists and [ ] for arrays:

Java

1String first = homes.get(0);2String firstArg = args[0];

Read more: Lists, sets and maps

void cannot be dereferenced

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:12: error: void cannot be dereferenced        String name = player.sendRichMessage("Hi").trim();                                                  ^1 error

What it means. A method that returns void gives back nothing, so you cannot put a dot after it to call something else.

Likely causes

Chaining a call after a method that only does something (like sendRichMessage).

How to fix it

Call the methods one after another on separate lines, or check the return type in the Javadoc.

Example:

Java

1player.sendRichMessage("Hi");2String name = player.getName().trim();

Read more: Methods: reusable actions

illegal character (curly quotes or other pasted symbol)

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:12: error: illegal character: '\u201c'        player.sendRichMessage(�<green>Welcome!�);                               ^C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:12: error: illegal start of expression        player.sendRichMessage(�<green>Welcome!�);                                       ^C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:12: error: ';' expected        player.sendRichMessage(�<green>Welcome!�);                                              ^C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\JoinListener.java:12: error: illegal character: '\u201d'        player.sendRichMessage(�<green>Welcome!�);                                               ^4 errors

What it means. The file contains a character that Java does not allow in code. When you copy code from a web page or a chat, straight quotes " are often replaced by curly quotes.

Likely causes

Smart quotes (“ and ”) from a web page, document or chat program.
A hidden character such as a non-breaking space.

How to fix it

Delete the strange character and type the normal character yourself.
Retype the quotes around text with the " key.
Paste into a plain text editor first, or use the Copy button on code blocks in this guide.

Read more: How code reads, Working with text

unmappable character for encoding windows-1252

What you see

C:\Users\Steve\IdeaProjects\my-plugin\src\main\java\com\example\myplugin\Messages.java:4: error: unmappable character (0x81) for encoding windows-1252    public static final String OWNER = "Ã?ngel";                                          ^1 error

What it means. The compiler read your source file with an old Windows character set, but the file was saved as UTF-8 and contains a letter or symbol that old set cannot show.

Likely causes

No -encoding UTF-8 setting for the compiler (Gradle uses the system default).
Special characters (accents, symbols) in your code.

How to fix it

Tell Gradle to read files as UTF-8 in build.gradle.kts:

build.gradle.kts

1tasks {2    compileJava {3        options.encoding = Charsets.UTF_8.name()4    }5}

In IntelliJ check File > Settings > Editor > File Encodings: both lines should say UTF-8.
Put the special characters into a config file instead of code when you can.

Plugin loading errors

Problems when the server starts and tries to load your plugin jar.

Jar does not contain plugin.yml

What you see

[14:02:09 ERROR]: Could not load 'plugins/my-plugin-1.0.0.jar' in folder 'plugins'org.bukkit.plugin.InvalidPluginException: Jar does not contain plugin.yml	at io.papermc.paper.plugin.provider.type.spigot.SpigotPluginProvider.createInstance(SpigotPluginProvider.java:141) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.provider.type.spigot.SpigotPluginProvider.createInstance(SpigotPluginProvider.java:36) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.entrypoint.strategy.modern.ModernPluginLoadingStrategy.loadProviders(ModernPluginLoadingStrategy.java:116) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	... 6 moreCaused by: java.io.FileNotFoundException: Jar does not contain plugin.yml

What it means. Paper opened your plugin's jar file and looked for plugin.yml, the small file that tells it the plugin's name and main class. It was not inside.

Likely causes

plugin.yml is not in src/main/resources, so Gradle did not pack it.
The file is called plugin.yaml, Plugin.yml or plugin.yml.txt.
You put a different jar (a library or a plain zip) in the plugins folder.

How to fix it

Open your project and check that the file is at src/main/resources/plugin.yml.
In File Explorer turn on "File name extensions" to make sure it is not named plugin.yml.txt.
Open the jar with a zip program (7-Zip works): plugin.yml must be in the top level of the jar.
Rebuild with .\gradlew.bat build and copy the jar from build\libs again.

plugin.yml is missing name, version or main

What you see

[14:02:09 ERROR]: Could not load 'plugins/my-plugin-1.0.0.jar' in folder 'plugins'org.bukkit.plugin.InvalidPluginException: org.bukkit.plugin.InvalidDescriptionException: main is not defined	at io.papermc.paper.plugin.provider.type.spigot.SpigotPluginProvider.createInstance(SpigotPluginProvider.java:141) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.provider.type.spigot.SpigotPluginProvider.createInstance(SpigotPluginProvider.java:36) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	... 7 moreCaused by: org.bukkit.plugin.InvalidDescriptionException: main is not defined	at org.bukkit.plugin.PluginDescriptionFile.loadMap(PluginDescriptionFile.java:1109) ~[paper-api-26.3.build.142-beta.jar:?]	... 10 moreCaused by: java.lang.NullPointerException: Cannot invoke "Object.toString()" because the return value of "java.util.Map.get(Object)" is null	at org.bukkit.plugin.PluginDescriptionFile.loadMap(PluginDescriptionFile.java:1106) ~[paper-api-26.3.build.142-beta.jar:?]	... 11 more

What it means. Every plugin needs three facts in plugin.yml: name, version and main. Paper read the file but one of them is not there.

Likely causes

The key is missing, or misspelled (mian:).
A space is missing after the colon (main:com.example...).
The key sits inside another section because of wrong indentation.

How to fix it

Check that these three lines exist at the very left edge of the file:

YAML

1name: MyPlugin2version: '1.0.0'3main: com.example.myplugin.MyPlugin4api-version: '26.3'

Write a space after every colon.
Use the plugin.yml Builder tool to generate a correct file.

Read more: plugin.yml explained, plugin.yml Builder

plugin.yml name contains invalid characters

What you see

[14:02:09 ERROR]: Could not load 'plugins/my-plugin-1.0.0.jar' in folder 'plugins'org.bukkit.plugin.InvalidPluginException: org.bukkit.plugin.InvalidDescriptionException: name 'My Plugin!' contains invalid characters.	at io.papermc.paper.plugin.provider.type.spigot.SpigotPluginProvider.createInstance(SpigotPluginProvider.java:141) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.provider.type.spigot.SpigotPluginProvider.createInstance(SpigotPluginProvider.java:36) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	... 7 moreCaused by: org.bukkit.plugin.InvalidDescriptionException: name 'My Plugin!' contains invalid characters.	at org.bukkit.plugin.PluginDescriptionFile.loadMap(PluginDescriptionFile.java:1084) ~[paper-api-26.3.build.142-beta.jar:?]	... 9 more

What it means. The plugin's name may only use letters, numbers, dots, dashes and underscores. A space or a special character breaks it.

Likely causes

A space in the name (My Plugin).
A symbol such as !, & or an accented letter.

How to fix it

Rename it, for example MyPlugin, My_Plugin or my-plugin.
Keep the display text for messages; the name is a technical id.

Read more: plugin.yml explained

Cannot find main class (wrong main: line in plugin.yml)

What you see

[14:02:09 ERROR]: Could not load 'plugins/my-plugin-1.0.0.jar' in folder 'plugins'org.bukkit.plugin.InvalidPluginException: Cannot find main class `com.example.myplugin.MyPlugn'	at io.papermc.paper.plugin.provider.type.spigot.SpigotPluginProvider.createInstance(SpigotPluginProvider.java:141) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.provider.type.spigot.SpigotPluginProvider.createInstance(SpigotPluginProvider.java:36) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.entrypoint.strategy.modern.ModernPluginLoadingStrategy.loadProviders(ModernPluginLoadingStrategy.java:116) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.storage.SimpleProviderStorage.enter(SimpleProviderStorage.java:39) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.entrypoint.LaunchEntryPointHandler.enter(LaunchEntryPointHandler.java:36) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.craftbukkit.CraftServer.loadPlugins(CraftServer.java:445) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.dedicated.DedicatedServer.initServer(DedicatedServer.java:288) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.MinecraftServer.runServer(MinecraftServer.java:1148) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at java.base/java.lang.Thread.run(Thread.java:1474) ~[?:?]Caused by: java.lang.ClassNotFoundException: com.example.myplugin.MyPlugn	at org.bukkit.plugin.java.PluginClassLoader.loadClass(PluginClassLoader.java:149) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.plugin.java.PluginClassLoader.loadClass(PluginClassLoader.java:112) ~[paper-api-26.3.build.142-beta.jar:?]	at java.base/java.lang.Class.forName0(Native Method) ~[?:?]	at java.base/java.lang.Class.forName(Class.java:578) ~[?:?]	... 8 more

What it means. Paper reads main: in plugin.yml, the full name of your main class, and tried to load that class from the jar. There is no class with exactly that name.

Likely causes

A typo in the main: line, or wrong capital letters.
The package name in plugin.yml does not match the package line in the class (or you moved/renamed the package).
The class is not in the jar because the build failed or the old jar is still in the plugins folder.

How to fix it

Open your main class and copy its package and name: the main: line must be package.ClassName.
Example (package com.example.myplugin, class MyPlugin):
YAML
```
1main: com.example.myplugin.MyPlugin
```
In IntelliJ right click the class and choose Copy Reference to get the full name.
After renaming a package, update plugin.yml too, rebuild, and replace the jar.

main class must extend JavaPlugin / needs a no-args constructor

What you see

[14:02:09 ERROR]: Could not load 'plugins/my-plugin-1.0.0.jar' in folder 'plugins'org.bukkit.plugin.InvalidPluginException: main class `com.example.myplugin.MyPlugin' must have a no-args constructor	at io.papermc.paper.plugin.provider.type.spigot.SpigotPluginProvider.createInstance(SpigotPluginProvider.java:141) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.provider.type.spigot.SpigotPluginProvider.createInstance(SpigotPluginProvider.java:36) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.entrypoint.strategy.modern.ModernPluginLoadingStrategy.loadProviders(ModernPluginLoadingStrategy.java:116) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.storage.SimpleProviderStorage.enter(SimpleProviderStorage.java:39) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.entrypoint.LaunchEntryPointHandler.enter(LaunchEntryPointHandler.java:36) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.craftbukkit.CraftServer.loadPlugins(CraftServer.java:445) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.dedicated.DedicatedServer.initServer(DedicatedServer.java:288) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.MinecraftServer.runServer(MinecraftServer.java:1148) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at java.base/java.lang.Thread.run(Thread.java:1474) ~[?:?]Caused by: java.lang.NoSuchMethodException: com.example.myplugin.MyPlugin.<init>()	at java.base/java.lang.Class.getConstructor0(Class.java:3761) ~[?:?]	at java.base/java.lang.Class.getDeclaredConstructor(Class.java:2930) ~[?:?]	... 9 more

What it means. Paper loaded the class named in main: but could not turn it into your plugin. The main class must be a normal class that extends JavaPlugin and has an empty constructor.

Likely causes

The class does not say extends JavaPlugin.
You added a constructor with parameters (MyPlugin(String x)).
The class is abstract, or an interface.
main: points to your listener or command class instead of the main class.

How to fix it

The main class should look like this:

Java

1public class MyPlugin extends JavaPlugin {2 3    @Override4    public void onEnable() {5        getLogger().info("MyPlugin is enabled");6    }7}

Remove any constructor with parameters. Put your setup code in onEnable instead.
Make sure main: names the class that extends JavaPlugin.

Plugin already initialized! (you created the plugin with new)

What you see

[14:02:12 ERROR]: Error occurred while enabling MyPlugin v1.0.0 (Is it up to date?)java.lang.IllegalArgumentException: Plugin already initialized!	at org.bukkit.plugin.java.PluginClassLoader.initialize(PluginClassLoader.java:301) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.plugin.java.JavaPlugin.<init>(JavaPlugin.java:70) ~[paper-api-26.3.build.142-beta.jar:?]	at com.example.myplugin.MyPlugin.<init>(MyPlugin.java:6) ~[my-plugin-1.0.0.jar:?]	at com.example.myplugin.JoinListener.<init>(JoinListener.java:9) ~[my-plugin-1.0.0.jar:?]	at com.example.myplugin.MyPlugin.onEnable(MyPlugin.java:12) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPlugin.setEnabled(JavaPlugin.java:285) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperPluginInstanceManager.enablePlugin(PaperPluginInstanceManager.java:200) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.enablePlugin(PaperPluginManagerImpl.java:104) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.enablePlugin(SimplePluginManager.java:507) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.craftbukkit.CraftServer.enablePlugin(CraftServer.java:560) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.craftbukkit.CraftServer.enablePlugins(CraftServer.java:493) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.MinecraftServer.loadWorld0(MinecraftServer.java:589) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]Caused by: java.lang.IllegalStateException: Initial initialization	at org.bukkit.plugin.java.PluginClassLoader.initialize(PluginClassLoader.java:304) ~[paper-api-26.3.build.142-beta.jar:?]	... 8 more

What it means. Paper creates exactly one object of your main class. If your own code does new MyPlugin(), Java tries to create a second one and Paper stops it.

Likely causes

new MyPlugin() somewhere in your code, often inside a listener or command class.
Several classes that all extends JavaPlugin.

How to fix it

Hand the existing plugin object to the classes that need it:

Java

1public class MyPlugin extends JavaPlugin {2 3    @Override4    public void onEnable() {5        getServer().getPluginManager().registerEvents(new JoinListener(this), this);6    }7}

And receive it in a constructor:

Java

1public class JoinListener implements Listener {2 3    private final MyPlugin plugin;4 5    public JoinListener(MyPlugin plugin) {6        this.plugin = plugin;7    }8}

Only one class in your plugin may extend JavaPlugin.

NoClassDefFoundError / ClassNotFoundException for a library class

What you see

[14:02:12 ERROR]: Error occurred while enabling MyPlugin v1.0.0 (Is it up to date?)java.lang.NoClassDefFoundError: com/zaxxer/hikari/HikariConfig	at com.example.myplugin.Database.connect(Database.java:18) ~[my-plugin-1.0.0.jar:?]	at com.example.myplugin.MyPlugin.onEnable(MyPlugin.java:21) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPlugin.setEnabled(JavaPlugin.java:285) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperPluginInstanceManager.enablePlugin(PaperPluginInstanceManager.java:200) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.enablePlugin(PaperPluginManagerImpl.java:104) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.enablePlugin(SimplePluginManager.java:507) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.craftbukkit.CraftServer.enablePlugin(CraftServer.java:560) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.craftbukkit.CraftServer.enablePlugins(CraftServer.java:493) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.MinecraftServer.loadWorld0(MinecraftServer.java:589) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]Caused by: java.lang.ClassNotFoundException: com.zaxxer.hikari.HikariConfig	at org.bukkit.plugin.java.PluginClassLoader.loadClass(PluginClassLoader.java:149) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.plugin.java.PluginClassLoader.loadClass(PluginClassLoader.java:112) ~[paper-api-26.3.build.142-beta.jar:?]	at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:526) ~[?:?]	... 14 more

What it means. Your code compiled because the library was on the compile path, but when the server runs your plugin that library is not there. Java cannot find a class that your code needs while it runs.

Likely causes

The library is declared compileOnly, so it was not packed into your jar, and the server does not have it either.
A plugin you depend on (Vault, PlaceholderAPI) is not installed on the server.
The plugin is not listed in depend or softdepend, so it loaded after yours.
A jar was built for a different version and a class was moved or removed.

How to fix it

Find the class name in the error (com/zaxxer/hikari/HikariConfig means the Hikari library).
For another plugin's classes, install that plugin on the server and list it under depend: in plugin.yml.
For a normal library (database pool, JSON), either let Paper download it with libraries: in plugin.yml, or pack it into your jar with the Shadow plugin.
Example: let the server download a library at startup:
YAML
```
1libraries:2  - com.zaxxer:HikariCP:6.2.1
```

Server will not start: LinkageError / class file version 69 (server Java too old)

What you see

Error: LinkageError occurred while loading main class io.papermc.paperclip.Main	java.lang.UnsupportedClassVersionError: io/papermc/paperclip/Main has been compiled by a more recent version of the Java Runtime (class file version 69.0), this version of the Java Runtime only recognizes class file versions up to 65.0

What it means. The Paper server file itself needs a newer Java than the one that started it. Paper 26.3 needs Java 25. Class file version 69 means Java 25, 65 means Java 21.

Likely causes

The java on your PATH is older (21 or 17) than Paper needs.
A start script (start.bat) points to an old Java.
A hosting panel is set to an older Java version.

How to fix it

Install Eclipse Temurin JDK 25.
Run java -version in the same window you start the server in. It must say 25.
In start.bat use the full path to the right Java, for example: "C:\Program Files\Eclipse Adoptium\jdk-25.0.4.101-hotspot\bin\java.exe" -jar paper.jar --nogui.
On a hosting panel choose Java 25 in the startup settings.

UnsupportedClassVersionError: plugin compiled for a newer Java than the server runs

What you see

[14:02:09 ERROR]: Could not load 'plugins/my-plugin-1.0.0.jar' in folder 'plugins'org.bukkit.plugin.InvalidPluginException: java.lang.UnsupportedClassVersionError: com/example/myplugin/MyPlugin has been compiled by a more recent version of the Java Runtime (class file version 69.0), this version of the Java Runtime only recognizes class file versions up to 65.0	at io.papermc.paper.plugin.provider.type.spigot.SpigotPluginProvider.createInstance(SpigotPluginProvider.java:141) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.provider.type.spigot.SpigotPluginProvider.createInstance(SpigotPluginProvider.java:36) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.entrypoint.strategy.modern.ModernPluginLoadingStrategy.loadProviders(ModernPluginLoadingStrategy.java:116) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.storage.SimpleProviderStorage.enter(SimpleProviderStorage.java:39) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.entrypoint.LaunchEntryPointHandler.enter(LaunchEntryPointHandler.java:36) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.craftbukkit.CraftServer.loadPlugins(CraftServer.java:445) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.dedicated.DedicatedServer.initServer(DedicatedServer.java:288) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.MinecraftServer.runServer(MinecraftServer.java:1148) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at java.base/java.lang.Thread.run(Thread.java:1474) ~[?:?]Caused by: java.lang.UnsupportedClassVersionError: com/example/myplugin/MyPlugin has been compiled by a more recent version of the Java Runtime (class file version 69.0), this version of the Java Runtime only recognizes class file versions up to 65.0	at java.base/java.lang.ClassLoader.defineClass1(Native Method) ~[?:?]	at java.base/java.lang.ClassLoader.defineClass(ClassLoader.java:1027) ~[?:?]	at java.base/java.security.SecureClassLoader.defineClass(SecureClassLoader.java:150) ~[?:?]	... 8 more

What it means. Your plugin was built with a newer Java than the server runs. Java marks every compiled class with a version number: 61 = Java 17, 65 = Java 21, 69 = Java 25. A server can only read classes up to its own number.

Likely causes

You built with JDK 25 but the server runs Java 21 or older (common on hosting panels).
The server is a Paper version older than 26.1 that still runs on Java 21.

How to fix it

Best fix: run the server on the Java version that matches the Paper version (Paper 26.3 needs Java 25).
If your plugin must run on an older server, compile for an older Java in build.gradle.kts:
build.gradle.kts
```
1java {2    toolchain.languageVersion = JavaLanguageVersion.of(21)3}
```
Use this table: class file 61 = Java 17, 65 = Java 21, 69 = Java 25.

Unsupported API version in plugin.yml

What you see

[14:02:09 ERROR]: Could not load 'plugins/my-plugin-1.0.0.jar' in folder 'plugins'org.bukkit.plugin.InvalidPluginException: Unsupported API version 26.9	at io.papermc.paper.plugin.provider.type.spigot.SpigotPluginProvider.createInstance(SpigotPluginProvider.java:141) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.provider.type.spigot.SpigotPluginProvider.createInstance(SpigotPluginProvider.java:36) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.entrypoint.strategy.modern.ModernPluginLoadingStrategy.loadProviders(ModernPluginLoadingStrategy.java:116) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.storage.SimpleProviderStorage.enter(SimpleProviderStorage.java:39) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.entrypoint.LaunchEntryPointHandler.enter(LaunchEntryPointHandler.java:36) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.craftbukkit.CraftServer.loadPlugins(CraftServer.java:445) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.dedicated.DedicatedServer.initServer(DedicatedServer.java:288) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.MinecraftServer.runServer(MinecraftServer.java:1148) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at java.base/java.lang.Thread.run(Thread.java:1474) ~[?:?]

What it means. api-version in plugin.yml names the Minecraft version your plugin was written for. Paper only accepts versions it knows, up to its own.

Likely causes

A version number from the future or a typo (26.9).
A newer plugin on an older Paper server.

How to fix it

Use the version of the server you run:
YAML
```
1api-version: '26.3'
```
Always put the version in quotes so YAML does not turn 1.20 into the number 1.2.
If the server is older than your plugin, update the server.

Read more: plugin.yml explained

Legacy plugin does not specify an api-version

What you see

[14:02:08 WARN]: Legacy plugin MyPlugin v1.0.0 does not specify an api-version.[14:02:08 INFO]: Initializing Legacy Material Support. Unless you have legacy plugins and/or data this is a bug!

What it means. Without an api-version, Paper assumes your plugin is very old and switches on slow compatibility code that renames old block and item names.

Likely causes

api-version is missing from plugin.yml.
The key is spelled differently (api_version, apiversion).

How to fix it

Add the line to plugin.yml:
YAML
```
1api-version: '26.3'
```
Rebuild and replace the jar.

Read more: plugin.yml explained

Ambiguous plugin name (two jars with the same plugin name)

What you see

[14:02:08 ERROR]: Ambiguous plugin name `MyPlugin' for files `plugins/my-plugin-1.0.0.jar' and `plugins/my-plugin-1.0.1.jar' in `plugins'

What it means. Two jar files in the plugins folder both say their name is MyPlugin. Paper cannot decide which one to load.

Likely causes

You copied a new version of your plugin into plugins without deleting the old jar.
The same plugin was downloaded twice.

How to fix it

Stop the server, delete the old jar from plugins, and start again.
Gradle names the jar after version in gradle.properties: every new version makes a new file name, so old ones pile up.
Use runServer (run-paper) while developing: it always loads only your latest build.

Unknown or missing dependency plugin (depend: in plugin.yml)

What you see

[14:02:09 ERROR]: Could not load 'plugins/shop-plugin-1.0.0.jar' in folder 'plugins'org.bukkit.plugin.UnknownDependencyException: Unknown/missing dependency plugins: [Vault]. Please download and install these plugins to run 'ShopPlugin'.	at io.papermc.paper.plugin.provider.type.spigot.SpigotPluginProvider.createInstance(SpigotPluginProvider.java:141) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.provider.type.spigot.SpigotPluginProvider.createInstance(SpigotPluginProvider.java:36) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.entrypoint.strategy.modern.ModernPluginLoadingStrategy.loadProviders(ModernPluginLoadingStrategy.java:116) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.storage.SimpleProviderStorage.enter(SimpleProviderStorage.java:39) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.entrypoint.LaunchEntryPointHandler.enter(LaunchEntryPointHandler.java:36) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.craftbukkit.CraftServer.loadPlugins(CraftServer.java:445) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.dedicated.DedicatedServer.initServer(DedicatedServer.java:288) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.MinecraftServer.runServer(MinecraftServer.java:1148) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at java.base/java.lang.Thread.run(Thread.java:1474) ~[?:?]

What it means. Your plugin.yml says your plugin cannot work without another plugin (depend:), and that other plugin is not in the plugins folder.

Likely causes

The other plugin (Vault, LuckPerms...) was never installed.
Its jar failed to load itself (look higher in the log).
The name in depend: is spelled differently from the other plugin's real name.

How to fix it

Install the plugin that is named in the message and restart the server.
Scroll up in the log: if the other plugin itself failed to load, fix that first.
Use softdepend when your plugin should still work without the other plugin:
YAML
```
1softdepend: [Vault]
```

Circular dependency detected

What you see

[14:02:08 ERROR]: Could not load 'plugins/plugin-a.jar': circular dependency detected[14:02:08 ERROR]: Could not load 'plugins/plugin-b.jar': circular dependency detected

What it means. Plugin A waits for plugin B to load first, and plugin B waits for plugin A. Neither can ever start.

Likely causes

Both plugins list each other in depend, softdepend or loadbefore.
A longer circle: A needs B, B needs C, C needs A.

How to fix it

Open both plugin.yml files and look at depend, softdepend and loadbefore.
Remove one of the links, so the dependency only goes one way.
Use softdepend on the side that can work without the other.

Paper plugin: getCommand does not work (commands in paper-plugin.yml)

What you see

[14:02:12 ERROR]: Error occurred while enabling MyPlugin v1.0.0 (Is it up to date?)java.lang.UnsupportedOperationException: You are trying to call JavaPlugin#getCommand on a Paper plugin during startup:you are probably trying to get a command you tried to define in paper-plugin.yml.Paper plugins do not support YAML-based command declarations!You can use JavaPlugin#registerCommand to define commands in Paper plugins.Please check the documentation for more information on how to define commands in Paper plugins: https://docs.papermc.io/paper/dev/getting-started/paper-plugins#commands	at org.bukkit.plugin.java.JavaPlugin.getCommand(JavaPlugin.java:355) ~[paper-api-26.3.build.142-beta.jar:?]	at com.example.myplugin.MyPlugin.onEnable(MyPlugin.java:9) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPlugin.setEnabled(JavaPlugin.java:285) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperPluginInstanceManager.enablePlugin(PaperPluginInstanceManager.java:200) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.enablePlugin(PaperPluginManagerImpl.java:104) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.enablePlugin(SimplePluginManager.java:507) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.craftbukkit.CraftServer.enablePlugin(CraftServer.java:560) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.craftbukkit.CraftServer.enablePlugins(CraftServer.java:493) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.MinecraftServer.loadWorld0(MinecraftServer.java:589) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]

What it means. paper-plugin.yml has no commands: section. Plugins that use it cannot declare commands in YAML the way plugin.yml plugins do, so getCommand("heal") has nothing to find.

Likely causes

You copied the commands: block and getCommand(...).setExecutor(...) from a plugin.yml tutorial into a Paper plugin.

How to fix it

Java

1@Override2public void onEnable() {3    registerCommand("heal", new HealCommand());4}

Or register a Brigadier command tree with LifecycleEvents.COMMANDS; see the commands chapters.
Or use plugin.yml instead of paper-plugin.yml if you want the classic way.

Error occurred while enabling plugin (onEnable crashed)

What you see

[14:02:12 ERROR]: Error occurred while enabling MyPlugin v1.0.0 (Is it up to date?)com.example.myplugin.SetupException: Database file could not be created	at com.example.myplugin.Database.open(Database.java:27) ~[my-plugin-1.0.0.jar:?]	at com.example.myplugin.MyPlugin.onEnable(MyPlugin.java:15) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPlugin.setEnabled(JavaPlugin.java:285) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperPluginInstanceManager.enablePlugin(PaperPluginInstanceManager.java:200) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.enablePlugin(PaperPluginManagerImpl.java:104) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.enablePlugin(SimplePluginManager.java:507) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.craftbukkit.CraftServer.enablePlugin(CraftServer.java:560) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.craftbukkit.CraftServer.enablePlugins(CraftServer.java:493) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.MinecraftServer.loadWorld0(MinecraftServer.java:589) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]

What it means. Something inside your onEnable method (or code it calls) threw an exception, so the plugin was switched off again right after it started. The real reason is the exception on the next line.

Likely causes

A missing file, a null value or a wrong setting during startup.
A plugin built for an older Paper version using something that no longer exists.

How to fix it

Read the line under the message: it names the exception. Look it up in this encyclopedia.
Find the first line that names your own package (like com.example.myplugin.Database.open(Database.java:27)): that is the line to fix.
Wrap risky setup in a check and log a clear message with getLogger().severe(...).

Invalid or corrupt jar file / zip END header not found

What you see

[14:02:09 ERROR]: Could not load 'plugins/my-plugin-1.0.0.jar' in folder 'plugins'org.bukkit.plugin.InvalidPluginException: java.util.zip.ZipException: zip END header not found	at io.papermc.paper.plugin.provider.type.spigot.SpigotPluginProvider.createInstance(SpigotPluginProvider.java:141) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.provider.type.spigot.SpigotPluginProvider.createInstance(SpigotPluginProvider.java:36) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.entrypoint.strategy.modern.ModernPluginLoadingStrategy.loadProviders(ModernPluginLoadingStrategy.java:116) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.storage.SimpleProviderStorage.enter(SimpleProviderStorage.java:39) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.entrypoint.LaunchEntryPointHandler.enter(LaunchEntryPointHandler.java:36) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.craftbukkit.CraftServer.loadPlugins(CraftServer.java:445) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.dedicated.DedicatedServer.initServer(DedicatedServer.java:288) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.MinecraftServer.runServer(MinecraftServer.java:1148) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at java.base/java.lang.Thread.run(Thread.java:1474) ~[?:?]Caused by: java.util.zip.ZipException: zip END header not found	at java.base/java.util.zip.ZipFile$Source.zerror(ZipFile.java:1648) ~[?:?]	at java.base/java.util.zip.ZipFile$Source.findEND(ZipFile.java:1569) ~[?:?]	... 9 more

What it means. Java tried to open the jar like a zip file and the file is damaged or incomplete.

Likely causes

The jar was copied while Gradle was still writing it.
A download or upload stopped early (the file is smaller than it should be).
The file was renamed from something that is not a jar, such as an HTML page.

How to fix it

Delete the jar from plugins and copy it again after the build says BUILD SUCCESSFUL.
Compare the file size on both sides. If it differs, upload again.
Open the jar with a zip program: if it cannot open it either, rebuild with .\gradlew.bat clean build.

Error occurred while disabling plugin

What you see

[14:30:41 ERROR]: Error occurred while disabling MyPlugin v1.0.0java.lang.IllegalStateException: Database connection is already closed	at com.example.myplugin.MyPlugin.onDisable(MyPlugin.java:31) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPlugin.setEnabled(JavaPlugin.java:285) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperPluginInstanceManager.disablePlugin(PaperPluginInstanceManager.java:236) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]

What it means. The server was stopping your plugin and your onDisable method threw an exception. Often it is a follow-up of an earlier failure in onEnable.

Likely causes

onDisable uses something that onEnable never created because onEnable stopped early.
Scheduling a task or registering something in onDisable.

How to fix it

Look for an earlier error in the log, from when the plugin started. Fix that first.

Guard values that may not exist:

Java

1@Override2public void onDisable() {3    if (database != null) {4        database.close();5    }6}

Could not load jar: restricted name or space in the file name

What you see

[14:02:08 ERROR]: Could not load 'plugins/my plugin.jar': uses the space-character (0x20) in its name

What it means. Paper refuses plugin jars that have a space in the file name or use a name reserved by the server.

Likely causes

The jar is named my plugin.jar or a download name like plugin (1).jar.

How to fix it

Rename the jar so it has no spaces: my-plugin.jar.
Stop the server before renaming files in plugins.

Read more: Build, install and test

Runtime exceptions and server errors

Crashes inside your code while the plugin runs, and common server start problems.

NullPointerException: a variable is null (because "name" is null)

What you see

[14:03:40 ERROR]: Could not pass event PlayerJoinEvent to MyPlugin v1.0.0org.bukkit.event.EventException: null	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:310) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.plugin.RegisteredListener.callEvent(RegisteredListener.java:71) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperEventManager.callEvent(PaperEventManager.java:54) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.callEvent(PaperPluginManagerImpl.java:131) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.callEvent(SimplePluginManager.java:628) ~[paper-api-26.3.build.142-beta.jar:?]	at net.minecraft.server.players.PlayerList.placeNewPlayer(PlayerList.java:342) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.network.ServerLoginPacketListenerImpl.placeNewPlayer(ServerLoginPacketListenerImpl.java:221) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]Caused by: java.lang.NullPointerException: Cannot invoke "org.bukkit.entity.Player.sendMessage(String)" because "target" is null	at com.example.myplugin.JoinListener.onJoin(JoinListener.java:12) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:306) ~[paper-api-26.3.build.142-beta.jar:?]	... 6 more

What it means. Your code used a variable as if it held an object, but the variable held nothing (null). Java's message names the exact variable (here target) and the action that failed.

Likely causes

The variable was set from a method that returned null (for example a player who is not online).
The variable was never given a value.
A search such as Bukkit.getPlayer("Steve") found nobody.

How to fix it

Look at the line named under "Your code" and find the variable from the message.
Find where that variable gets its value and check whether it can be null.

Check for null before using it:

Java

1Player target = Bukkit.getPlayer(name);2if (target == null) {3    sender.sendRichMessage("<red>That player is not online.");4    return true;5}6target.sendRichMessage("<green>Hello!");

NullPointerException: a field is null (because "this.x" is null)

What you see

[14:03:40 ERROR]: Could not pass event PlayerCommandPreprocessEvent to MyPlugin v1.0.0org.bukkit.event.EventException: null	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:310) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.plugin.RegisteredListener.callEvent(RegisteredListener.java:71) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperEventManager.callEvent(PaperEventManager.java:54) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.callEvent(PaperPluginManagerImpl.java:131) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.callEvent(SimplePluginManager.java:628) ~[paper-api-26.3.build.142-beta.jar:?]	at net.minecraft.server.players.PlayerList.placeNewPlayer(PlayerList.java:342) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.network.ServerLoginPacketListenerImpl.placeNewPlayer(ServerLoginPacketListenerImpl.java:221) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]Caused by: java.lang.NullPointerException: Cannot invoke "java.util.Map.get(Object)" because "this.homes" is null	at com.example.myplugin.HomeManager.findHome(HomeManager.java:7) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:306) ~[paper-api-26.3.build.142-beta.jar:?]	... 6 more

What it means. A field of your class (a variable that lives in the object, written this.homes) was never filled with a value, so using it fails.

Likely causes

The field was declared (private Map<String, String> homes;) but never created with new.
The field is set in onEnable, but the code that uses it runs before onEnable.
Your own class was created with new before the plugin gave it its data.

How to fix it

Create the object when you declare the field:

Java

1private final Map<String, String> homes = new HashMap<>();

Or fill it in the constructor, and make sure the constructor really runs.
Do not create your plugin class with new: Paper creates it once. Pass it to other classes through their constructor.

NullPointerException: a method returned null (because the return value of ... is null)

What you see

[14:05:09 ERROR]: nullorg.bukkit.command.CommandException: Unhandled exception executing command 'msg' in plugin MyPlugin v1.0.0	at org.bukkit.command.PluginCommand.execute(PluginCommand.java:47) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.command.SimpleCommandMap.dispatch(SimpleCommandMap.java:152) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.craftbukkit.CraftServer.dispatchCommand(CraftServer.java:1034) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.commands.Commands.performCommand(Commands.java:301) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]Caused by: java.lang.NullPointerException: Cannot invoke "org.bukkit.entity.Player.sendRichMessage(String)" because the return value of "org.bukkit.Bukkit.getPlayer(String)" is null	at com.example.myplugin.MsgCommand.onCommand(MsgCommand.java:24) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.command.PluginCommand.execute(PluginCommand.java:43) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.command.PluginCommand.execute(PluginCommand.java:43) ~[paper-api-26.3.build.142-beta.jar:?]	... 3 more

What it means. You chained a call onto a method (here Bukkit.getPlayer(...)) that can return null. When it returned nothing, the next call crashed. The message names the method that gave null.

Likely causes

Bukkit.getPlayer(name) returns null when no player with that name is online.
config.getString(...), map.get(...) and getItemMeta() also return null when they find nothing.

How to fix it

Store the result in a variable and check it:

Java

1Player target = Bukkit.getPlayer(args[0]);2if (target == null) {3    sender.sendRichMessage("<red>Player not found.");4    return true;5}6target.sendRichMessage(message);

Read the Javadoc: methods that can return null are marked @Nullable.

NullPointerException in onEnable: getCommand(...) returned null

What you see

[14:02:12 ERROR]: Error occurred while enabling MyPlugin v1.0.0 (Is it up to date?)java.lang.NullPointerException: Cannot invoke "org.bukkit.command.PluginCommand.setExecutor(org.bukkit.command.CommandExecutor)" because the return value of "com.example.myplugin.MyPlugin.getCommand(String)" is null	at com.example.myplugin.MyPlugin.onEnable(MyPlugin.java:9) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPlugin.setEnabled(JavaPlugin.java:285) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperPluginInstanceManager.enablePlugin(PaperPluginInstanceManager.java:200) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.enablePlugin(PaperPluginManagerImpl.java:104) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.enablePlugin(SimplePluginManager.java:507) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.craftbukkit.CraftServer.enablePlugin(CraftServer.java:560) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.craftbukkit.CraftServer.enablePlugins(CraftServer.java:493) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.MinecraftServer.loadWorld0(MinecraftServer.java:589) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]

What it means. getCommand("heal") looks the command up in your plugin.yml. It found nothing and returned null, and the next call (setExecutor) crashed. Your plugin was disabled because of this.

Likely causes

The command is not listed under commands: in plugin.yml, or the name differs (heel).
plugin.yml has a YAML problem so commands: is empty.
It is a Paper plugin (paper-plugin.yml): that file has no commands:.
You are testing an old jar that does not have the new command yet.

How to fix it

Declare the command in plugin.yml with exactly the same name:

YAML

1commands:2  heal:3    description: Heal yourself4    usage: /heal

Rebuild, replace the jar and restart the server.
Or use the modern way: register the command in code with Brigadier (no plugin.yml entry needed).

NullPointerException: getItemMeta() returned null

What you see

[14:03:40 ERROR]: Could not pass event PlayerInteractEvent to MyPlugin v1.0.0org.bukkit.event.EventException: null	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:310) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.plugin.RegisteredListener.callEvent(RegisteredListener.java:71) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperEventManager.callEvent(PaperEventManager.java:54) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.callEvent(PaperPluginManagerImpl.java:131) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.callEvent(SimplePluginManager.java:628) ~[paper-api-26.3.build.142-beta.jar:?]	at net.minecraft.server.players.PlayerList.placeNewPlayer(PlayerList.java:342) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.network.ServerLoginPacketListenerImpl.placeNewPlayer(ServerLoginPacketListenerImpl.java:221) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]Caused by: java.lang.NullPointerException: Cannot invoke "org.bukkit.inventory.meta.ItemMeta.displayName(net.kyori.adventure.text.Component)" because "meta" is null	at com.example.myplugin.ItemNamer.rename(ItemNamer.java:8) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:306) ~[paper-api-26.3.build.142-beta.jar:?]	... 6 more

What it means. item.getItemMeta() gives null for items that have no meta, such as air (an empty hand or empty slot).

Likely causes

The player's hand or the slot was empty (the item is AIR).

How to fix it

Check the item first, and check the meta:

Java

1ItemStack item = player.getInventory().getItemInMainHand();2if (item.isEmpty()) {3    return;4}5item.editMeta(meta -> meta.displayName(Component.text("Renamed")));

editMeta does the null check for you and applies the change safely.

NullPointerException: reading a number out of a Map (Integer.intValue)

What you see

[14:03:40 ERROR]: Could not pass event PlayerJoinEvent to MyPlugin v1.0.0org.bukkit.event.EventException: null	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:310) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.plugin.RegisteredListener.callEvent(RegisteredListener.java:71) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperEventManager.callEvent(PaperEventManager.java:54) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.callEvent(PaperPluginManagerImpl.java:131) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.callEvent(SimplePluginManager.java:628) ~[paper-api-26.3.build.142-beta.jar:?]	at net.minecraft.server.players.PlayerList.placeNewPlayer(PlayerList.java:342) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.network.ServerLoginPacketListenerImpl.placeNewPlayer(ServerLoginPacketListenerImpl.java:221) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]Caused by: java.lang.NullPointerException: Cannot invoke "java.lang.Integer.intValue()" because the return value of "java.util.Map.get(Object)" is null	at com.example.myplugin.CooldownManager.secondsLeft(CooldownManager.java:19) ~[my-plugin-1.0.0.jar:?]	at com.example.myplugin.JoinListener.onJoin(JoinListener.java:15) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:306) ~[paper-api-26.3.build.142-beta.jar:?]	... 6 more

What it means. A Map<UUID, Integer> returns null for a key it does not contain. Assigning that to a plain int makes Java try to unwrap the number, which crashes.

Likely causes

int seconds = cooldowns.get(uuid); for a player who has no entry yet.

How to fix it

Use getOrDefault to give a fallback value:

Java

1int seconds = cooldowns.getOrDefault(player.getUniqueId(), 0);

Or use Integer (the object type) and check for null yourself.

NullPointerException with <local4> instead of a variable name

What you see

[14:03:40 ERROR]: Could not pass event PlayerJoinEvent to MyPlugin v1.0.0org.bukkit.event.EventException: null	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:310) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.plugin.RegisteredListener.callEvent(RegisteredListener.java:71) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperEventManager.callEvent(PaperEventManager.java:54) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.callEvent(PaperPluginManagerImpl.java:131) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.callEvent(SimplePluginManager.java:628) ~[paper-api-26.3.build.142-beta.jar:?]	at net.minecraft.server.players.PlayerList.placeNewPlayer(PlayerList.java:342) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.network.ServerLoginPacketListenerImpl.placeNewPlayer(ServerLoginPacketListenerImpl.java:221) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]Caused by: java.lang.NullPointerException: Cannot invoke "String.length()" because "<local4>" is null	at com.example.myplugin.NameChecker.check(NameChecker.java:14) ~[my-plugin-1.0.0.jar:?]	at com.example.myplugin.JoinListener.onJoin(JoinListener.java:11) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:306) ~[paper-api-26.3.build.142-beta.jar:?]	... 6 more

What it means. This is the same null problem as the others, but the compiler did not keep variable names in the jar, so Java can only say it is the fourth local variable (<local4>).

Likely causes

The jar was compiled without debug information.

How to fix it

Count the local variables and parameters in the method from the top: the fourth one is the null one. (For instance methods, this is number 0.)
Or look at the line shown under "Your code" and check every variable it uses.
Gradle normally includes variable names. If they are missing, make sure you build with Gradle (.\gradlew.bat build) and not with a custom command.

NullPointerException (null used as an object)

What you see

[14:08:30 ERROR]: Could not pass event PlayerQuitEvent to MyPlugin v1.0.0org.bukkit.event.EventException: null	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:310) ~[paper-api-26.3.build.142-beta.jar:?]Caused by: java.lang.NullPointerException	at java.base/java.util.Objects.requireNonNull(Objects.java:233) ~[?:?]	at com.example.myplugin.QuitListener.onQuit(QuitListener.java:14) ~[my-plugin-1.0.0.jar:?]	... 6 more

What it means. null means "no object here". A NullPointerException happens when code tries to use null like a real object. This one has no detail message, so the line number under "Your code" is your best clue.

Likely causes

A value was never set, or a method returned null.
Objects.requireNonNull(...) or throw new NullPointerException() was used on purpose.

How to fix it

Open the file and line shown under "Your code".
On that line, find each thing with a dot after it (a.b()): a is the one that might be null.
Add a null check, or find out why the value is missing.

ClassCastException: console cannot be cast to Player

What you see

[14:05:09 ERROR]: nullorg.bukkit.command.CommandException: Unhandled exception executing command 'heal' in plugin MyPlugin v1.0.0	at org.bukkit.command.PluginCommand.execute(PluginCommand.java:47) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.command.SimpleCommandMap.dispatch(SimpleCommandMap.java:152) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.craftbukkit.CraftServer.dispatchCommand(CraftServer.java:1034) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.commands.Commands.performCommand(Commands.java:301) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]Caused by: java.lang.ClassCastException: class org.bukkit.craftbukkit.command.CraftConsoleCommandSender cannot be cast to class org.bukkit.entity.Player (org.bukkit.craftbukkit.command.CraftConsoleCommandSender and org.bukkit.entity.Player are in unnamed module of loader java.net.URLClassLoader @3e3abc88)	at com.example.myplugin.HealCommand.onCommand(HealCommand.java:18) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.command.PluginCommand.execute(PluginCommand.java:43) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.command.PluginCommand.execute(PluginCommand.java:43) ~[paper-api-26.3.build.142-beta.jar:?]	... 3 more

What it means. Someone typed your command in the server console. The console is a command sender, but it is not a Player, so the line (Player) sender fails.

Likely causes

A cast (Player) sender without checking the sender first.
The command was run from the console, a command block or RCON.

How to fix it

Check with instanceof first and answer politely if it is not a player:

Java

1if (!(sender instanceof Player player)) {2    sender.sendRichMessage("<red>Only players can use this command.");3    return true;4}5player.setHealth(player.getAttribute(Attribute.MAX_HEALTH).getValue());

ClassCastException: X cannot be cast to Y

What you see

[14:03:40 ERROR]: Could not pass event InventoryClickEvent to MyPlugin v1.0.0org.bukkit.event.EventException: null	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:310) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.plugin.RegisteredListener.callEvent(RegisteredListener.java:71) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperEventManager.callEvent(PaperEventManager.java:54) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.callEvent(PaperPluginManagerImpl.java:131) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.callEvent(SimplePluginManager.java:628) ~[paper-api-26.3.build.142-beta.jar:?]	at net.minecraft.server.players.PlayerList.placeNewPlayer(PlayerList.java:342) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.network.ServerLoginPacketListenerImpl.placeNewPlayer(ServerLoginPacketListenerImpl.java:221) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]Caused by: java.lang.ClassCastException: class java.lang.String cannot be cast to class java.lang.Integer (java.lang.String and java.lang.Integer are in module java.base of loader 'bootstrap')	at com.example.myplugin.ShopListener.onClick(ShopListener.java:27) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:306) ~[paper-api-26.3.build.142-beta.jar:?]	... 6 more

What it means. Your code treated an object as a type it is not. The message names both types: it was a String but the code needed an Integer.

Likely causes

A cast (Type) value on something that is another type.
A value read from a config file or map that has a different type than expected.
A wrong guess about which object an event gives (for example getWhoClicked() is not always the player you expect).

How to fix it

Check the type before casting:

Java

1if (value instanceof Integer amount) {2    player.sendRichMessage("Amount: " + amount);3}

For config values use the typed getters (getInt, getString) instead of casting.

NumberFormatException: For input string

What you see

[14:05:09 ERROR]: nullorg.bukkit.command.CommandException: Unhandled exception executing command 'pay' in plugin MyPlugin v1.0.0	at org.bukkit.command.PluginCommand.execute(PluginCommand.java:47) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.command.SimpleCommandMap.dispatch(SimpleCommandMap.java:152) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.craftbukkit.CraftServer.dispatchCommand(CraftServer.java:1034) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.commands.Commands.performCommand(Commands.java:301) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]Caused by: java.lang.NumberFormatException: For input string: "ten"	at java.base/java.lang.NumberFormatException.forInputString(NumberFormatException.java:67)	at java.base/java.lang.Integer.parseInt(Integer.java:565)	at java.base/java.lang.Integer.parseInt(Integer.java:662)	at com.example.myplugin.PayCommand.onCommand(PayCommand.java:22) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.command.PluginCommand.execute(PluginCommand.java:43) ~[paper-api-26.3.build.142-beta.jar:?]	... 3 more

What it means. Your code tried to turn text into a number (Integer.parseInt, Double.parseDouble), and the text was not a number. The quoted part shows the text it received.

Likely causes

A player typed a word where a number was expected (/pay Steve ten).
Spaces or symbols in the text ("5 ", "$5").
An empty value in a config file.

How to fix it

Catch the problem and tell the player what is wrong:

Java

1try {2    int amount = Integer.parseInt(args[1]);3} catch (NumberFormatException exception) {4    sender.sendRichMessage("<red>That is not a number.");5}

Call .trim() on the text first if spaces are possible.

ArrayIndexOutOfBoundsException: Index 0 out of bounds for length 0 (command arguments)

What you see

[14:05:09 ERROR]: nullorg.bukkit.command.CommandException: Unhandled exception executing command 'heal' in plugin MyPlugin v1.0.0	at org.bukkit.command.PluginCommand.execute(PluginCommand.java:47) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.command.SimpleCommandMap.dispatch(SimpleCommandMap.java:152) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.craftbukkit.CraftServer.dispatchCommand(CraftServer.java:1034) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.commands.Commands.performCommand(Commands.java:301) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]Caused by: java.lang.ArrayIndexOutOfBoundsException: Index 0 out of bounds for length 0	at com.example.myplugin.HealCommand.onCommand(HealCommand.java:19) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.command.PluginCommand.execute(PluginCommand.java:43) ~[paper-api-26.3.build.142-beta.jar:?]	... 3 more

What it means. You read an item from an array (args[0]) that is shorter than you assumed. Index 0 ... length 0 says the array is empty: the player typed the command without extra words.

Likely causes

args[0] used without checking args.length.
A command such as /heal typed with no player name.

How to fix it

Check the length before reading:

Java

1if (args.length < 1) {2    sender.sendRichMessage("<red>Usage: /heal <player>");3    return true;4}5String targetName = args[0];

Remember that indexes start at 0: an array with 3 items has indexes 0, 1 and 2.

IndexOutOfBoundsException: Index 3 out of bounds for length 3 (list)

What you see

[14:03:40 ERROR]: Could not pass event PlayerInteractEvent to MyPlugin v1.0.0org.bukkit.event.EventException: null	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:310) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.plugin.RegisteredListener.callEvent(RegisteredListener.java:71) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperEventManager.callEvent(PaperEventManager.java:54) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.callEvent(PaperPluginManagerImpl.java:131) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.callEvent(SimplePluginManager.java:628) ~[paper-api-26.3.build.142-beta.jar:?]	at net.minecraft.server.players.PlayerList.placeNewPlayer(PlayerList.java:342) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.network.ServerLoginPacketListenerImpl.placeNewPlayer(ServerLoginPacketListenerImpl.java:221) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]Caused by: java.lang.IndexOutOfBoundsException: Index 3 out of bounds for length 3	at java.base/jdk.internal.util.Preconditions.outOfBounds(Preconditions.java:100)	at java.base/jdk.internal.util.Preconditions.outOfBoundsCheckIndex(Preconditions.java:106)	at java.base/jdk.internal.util.Preconditions.checkIndex(Preconditions.java:302)	at java.base/java.util.Objects.checkIndex(Objects.java:365)	at java.base/java.util.ArrayList.get(ArrayList.java:428)	at com.example.myplugin.HomeMenu.open(HomeMenu.java:31) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:306) ~[paper-api-26.3.build.142-beta.jar:?]	... 6 more

What it means. You asked a list for an item at a position that does not exist. A list with 3 items has positions 0, 1 and 2, so position 3 is one too far.

Likely causes

A loop that goes to size() instead of stopping before it (i <= list.size()).
An empty list, because nothing was added yet.
A position stored earlier that is no longer valid after items were removed.

How to fix it

Loop with <, not <=:

Java

1for (int i = 0; i < homes.size(); i++) {2    player.sendRichMessage(homes.get(i));3}

Check list.isEmpty() or list.size() before calling get.
Or use a for-each loop, which cannot go too far: for (String home : homes) { ... }.

StringIndexOutOfBoundsException (substring or charAt too far)

What you see

[14:03:40 ERROR]: Could not pass event AsyncChatEvent to MyPlugin v1.0.0org.bukkit.event.EventException: null	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:310) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.plugin.RegisteredListener.callEvent(RegisteredListener.java:71) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperEventManager.callEvent(PaperEventManager.java:54) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.callEvent(PaperPluginManagerImpl.java:131) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.callEvent(SimplePluginManager.java:628) ~[paper-api-26.3.build.142-beta.jar:?]	at net.minecraft.server.players.PlayerList.placeNewPlayer(PlayerList.java:342) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.network.ServerLoginPacketListenerImpl.placeNewPlayer(ServerLoginPacketListenerImpl.java:221) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]Caused by: java.lang.StringIndexOutOfBoundsException: Range [0, 5) out of bounds for length 3	at java.base/jdk.internal.util.Preconditions$1.apply(Preconditions.java:55)	at java.base/jdk.internal.util.Preconditions$1.apply(Preconditions.java:52)	at java.base/jdk.internal.util.Preconditions$4.apply(Preconditions.java:213)	at java.base/jdk.internal.util.Preconditions$4.apply(Preconditions.java:210)	at java.base/jdk.internal.util.Preconditions.outOfBounds(Preconditions.java:98)	at java.base/jdk.internal.util.Preconditions.outOfBoundsCheckFromToIndex(Preconditions.java:112)	at java.base/jdk.internal.util.Preconditions.checkFromToIndex(Preconditions.java:349)	at java.base/java.lang.String.checkBoundsBeginEnd(String.java:4937)	at java.base/java.lang.String.substring(String.java:2899)	at com.example.myplugin.NameFormatter.shorten(NameFormatter.java:12) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:306) ~[paper-api-26.3.build.142-beta.jar:?]	... 6 more

What it means. You cut a piece out of a text with positions that go past its end. Range [0, 5) out of bounds for length 3 means: you asked for the first 5 letters of a 3-letter text.

Likely causes

substring(0, 5) on a text that is shorter than 5.
charAt(i) with i too big, or on an empty text.

How to fix it

Take the smaller of the two numbers:

Java

1String shortName = name.substring(0, Math.min(5, name.length()));

Check text.isEmpty() before charAt(0).

Read more: Working with text

IllegalArgumentException: No enum constant (Material.valueOf)

What you see

[14:03:40 ERROR]: Could not pass event PlayerJoinEvent to MyPlugin v1.0.0org.bukkit.event.EventException: null	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:310) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.plugin.RegisteredListener.callEvent(RegisteredListener.java:71) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperEventManager.callEvent(PaperEventManager.java:54) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.callEvent(PaperPluginManagerImpl.java:131) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.callEvent(SimplePluginManager.java:628) ~[paper-api-26.3.build.142-beta.jar:?]	at net.minecraft.server.players.PlayerList.placeNewPlayer(PlayerList.java:342) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.network.ServerLoginPacketListenerImpl.placeNewPlayer(ServerLoginPacketListenerImpl.java:221) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]Caused by: java.lang.IllegalArgumentException: No enum constant org.bukkit.Material.DIAMOND_SWORDD	at java.base/java.lang.Enum.valueOf(Enum.java:293)	at org.bukkit.Material.valueOf(Material.java:147)	at com.example.myplugin.MaterialPicker.pick(MaterialPicker.java:7) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:306) ~[paper-api-26.3.build.142-beta.jar:?]	... 6 more

What it means. valueOf("...") turns text into an enum value, such as a Material. There is no value with exactly the text you gave (maybe a typo, or an item that was renamed).

Likely causes

A typo in a config file (DIAMOND_SWORDD).
A lowercase name when upper case is needed.
A name from an older Minecraft version that no longer exists.

How to fix it

Use matchMaterial, which returns null instead of crashing:

Java

1Material material = Material.matchMaterial(text);2if (material == null) {3    sender.sendRichMessage("<red>Unknown item: " + text);4    return;5}

For enums you wrote yourself, catch IllegalArgumentException around valueOf.
Look up the exact names with the Names Lookup tool.

InvalidKeyException: Non [a-z0-9/._-] character in Key

What you see

[14:02:12 ERROR]: Error occurred while enabling MyPlugin v1.0.0 (Is it up to date?)net.kyori.adventure.key.InvalidKeyException: Non [a-z0-9/._-] character in value of Key[myplugin:Magic Wand] at index 0 ('M', bytes: [77])	at net.kyori.adventure.key.KeyImpl.checkError(KeyImpl.java:55) ~[paper-api-26.3.build.142-beta.jar:?]	at net.kyori.adventure.key.KeyImpl.<init>(KeyImpl.java:98) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.NamespacedKey.<init>(NamespacedKey.java:60) ~[paper-api-26.3.build.142-beta.jar:?]	at com.example.myplugin.Recipes.registerWand(Recipes.java:14) ~[my-plugin-1.0.0.jar:?]	at com.example.myplugin.MyPlugin.onEnable(MyPlugin.java:17) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPlugin.setEnabled(JavaPlugin.java:285) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperPluginInstanceManager.enablePlugin(PaperPluginInstanceManager.java:200) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.enablePlugin(PaperPluginManagerImpl.java:104) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.enablePlugin(SimplePluginManager.java:507) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.craftbukkit.CraftServer.enablePlugin(CraftServer.java:560) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.craftbukkit.CraftServer.enablePlugins(CraftServer.java:493) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.MinecraftServer.loadWorld0(MinecraftServer.java:589) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]

What it means. A NamespacedKey (the id of a recipe, an item or a data key) may only contain lowercase letters, digits and . _ - /. Capital letters and spaces are not allowed.

Likely causes

A capital letter or space in the key name (Magic Wand).
A key built from a player's name or a display name.

How to fix it

Use lowercase letters with underscores:

Java

1NamespacedKey key = new NamespacedKey(plugin, "magic_wand");

If the key comes from user text, lowercase it and replace spaces: text.toLowerCase().replace(' ', '_').

IllegalArgumentException: Plugin cannot be null (or another API argument)

What you see

[14:02:12 ERROR]: Error occurred while enabling MyPlugin v1.0.0 (Is it up to date?)java.lang.IllegalArgumentException: Plugin cannot be null	at com.google.common.base.Preconditions.checkArgument(Preconditions.java:143) ~[guava-33.6.0-jre.jar:?]	at org.bukkit.craftbukkit.scheduler.CraftScheduler.runTaskTimer(CraftScheduler.java:231) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at com.example.myplugin.Timers.start(Timers.java:12) ~[my-plugin-1.0.0.jar:?]	at com.example.myplugin.MyPlugin.onEnable(MyPlugin.java:14) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPlugin.setEnabled(JavaPlugin.java:285) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperPluginInstanceManager.enablePlugin(PaperPluginInstanceManager.java:200) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.enablePlugin(PaperPluginManagerImpl.java:104) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.enablePlugin(SimplePluginManager.java:507) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.craftbukkit.CraftServer.enablePlugin(CraftServer.java:560) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.craftbukkit.CraftServer.enablePlugins(CraftServer.java:493) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.MinecraftServer.loadWorld0(MinecraftServer.java:589) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]

What it means. You passed null to a method that does not accept it. The message says which argument was missing (Plugin, Listener, ...).

Likely causes

A plugin field that was never filled (your class got null from its constructor).
A value from Bukkit.getPlayer(...) or Material.getMaterial(...) that was null and passed straight on.

How to fix it

Find the line under "Your code" and see which variable is passed there.
Make sure your classes receive the real plugin through their constructor (this) and store it in a field.
Check results for null before you pass them on.

IllegalArgumentException: Health must be between 0 and max

What you see

[14:05:09 ERROR]: nullorg.bukkit.command.CommandException: Unhandled exception executing command 'heal' in plugin MyPlugin v1.0.0	at org.bukkit.command.PluginCommand.execute(PluginCommand.java:47) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.command.SimpleCommandMap.dispatch(SimpleCommandMap.java:152) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.craftbukkit.CraftServer.dispatchCommand(CraftServer.java:1034) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.commands.Commands.performCommand(Commands.java:301) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]Caused by: java.lang.IllegalArgumentException: Health must be between 0 and 20.0, but was 25.0. (attribute base value: 20.0)	at org.bukkit.craftbukkit.entity.CraftLivingEntity.setHealth(CraftLivingEntity.java:288) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at com.example.myplugin.HealCommand.onCommand(HealCommand.java:21) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.command.PluginCommand.execute(PluginCommand.java:43) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.command.PluginCommand.execute(PluginCommand.java:43) ~[paper-api-26.3.build.142-beta.jar:?]	... 3 more

What it means. setHealth only accepts values from 0 up to the player's current maximum health. You tried to set a number above that maximum.

Likely causes

Adding health without limiting the result (getHealth() + 10).
Using 20 as the maximum when another plugin or an effect changed it.

How to fix it

Read the real maximum and stay below it:

Java

1double max = player.getAttribute(Attribute.MAX_HEALTH).getValue();2player.setHealth(Math.min(max, player.getHealth() + 10));

IllegalArgumentException: Cannot measure distance between two worlds

What you see

[14:03:40 ERROR]: Could not pass event PlayerMoveEvent to MyPlugin v1.0.0org.bukkit.event.EventException: null	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:310) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.plugin.RegisteredListener.callEvent(RegisteredListener.java:71) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperEventManager.callEvent(PaperEventManager.java:54) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.callEvent(PaperPluginManagerImpl.java:131) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.callEvent(SimplePluginManager.java:628) ~[paper-api-26.3.build.142-beta.jar:?]	at net.minecraft.server.players.PlayerList.placeNewPlayer(PlayerList.java:342) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.network.ServerLoginPacketListenerImpl.placeNewPlayer(ServerLoginPacketListenerImpl.java:221) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]Caused by: java.lang.IllegalArgumentException: Cannot measure distance between world and world_nether	at com.google.common.base.Preconditions.checkArgument(Preconditions.java:230) ~[guava-33.6.0-jre.jar:?]	at org.bukkit.Location.distanceSquared(Location.java:612) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.Location.distance(Location.java:596) ~[paper-api-26.3.build.142-beta.jar:?]	at com.example.myplugin.CompassTask.run(CompassTask.java:25) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:306) ~[paper-api-26.3.build.142-beta.jar:?]	... 6 more

What it means. You asked for the distance between two locations that are in different worlds. That has no meaning, so Paper stops you.

Likely causes

A player in the nether compared with a spawn point in the overworld.

How to fix it

Compare the worlds first:

Java

1Location spawn = spawnLocation;2if (player.getWorld().equals(spawn.getWorld())) {3    double distance = player.getLocation().distance(spawn);4}

Read more: Worlds, locations and movement

IllegalArgumentException: enchantment level or enchantment cannot be applied

What you see

[14:03:40 ERROR]: Could not pass event PlayerJoinEvent to MyPlugin v1.0.0org.bukkit.event.EventException: null	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:310) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.plugin.RegisteredListener.callEvent(RegisteredListener.java:71) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperEventManager.callEvent(PaperEventManager.java:54) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.callEvent(PaperPluginManagerImpl.java:131) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.callEvent(SimplePluginManager.java:628) ~[paper-api-26.3.build.142-beta.jar:?]	at net.minecraft.server.players.PlayerList.placeNewPlayer(PlayerList.java:342) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.network.ServerLoginPacketListenerImpl.placeNewPlayer(ServerLoginPacketListenerImpl.java:221) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]Caused by: java.lang.IllegalArgumentException: Enchantment level is either too low or too high (given 10, bounds are 1 to 5)	at org.bukkit.inventory.ItemStack.addEnchantment(ItemStack.java:437) ~[paper-api-26.3.build.142-beta.jar:?]	at com.example.myplugin.WandFactory.create(WandFactory.java:22) ~[my-plugin-1.0.0.jar:?]	at com.example.myplugin.JoinListener.onJoin(JoinListener.java:13) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:306) ~[paper-api-26.3.build.142-beta.jar:?]	... 6 more

What it means. addEnchantment is the strict version: it refuses levels outside the normal range and enchantments that do not fit the item.

Likely causes

A level above the normal maximum (Sharpness 10 when the max is 5).
An enchantment that does not belong on that item (Sharpness on a pickaxe).

How to fix it

Use addUnsafeEnchantment when you want any level or item:
Java
```
1item.addUnsafeEnchantment(Enchantment.SHARPNESS, 10);
```
Or keep the level within the limits shown in the message.

Read more: Items and ItemStacks

IllegalStateException: Cannot set lore on AIR (item without meta)

What you see

[14:03:40 ERROR]: Could not pass event InventoryClickEvent to MyPlugin v1.0.0org.bukkit.event.EventException: null	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:310) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.plugin.RegisteredListener.callEvent(RegisteredListener.java:71) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperEventManager.callEvent(PaperEventManager.java:54) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.callEvent(PaperPluginManagerImpl.java:131) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.callEvent(SimplePluginManager.java:628) ~[paper-api-26.3.build.142-beta.jar:?]	at net.minecraft.server.players.PlayerList.placeNewPlayer(PlayerList.java:342) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.network.ServerLoginPacketListenerImpl.placeNewPlayer(ServerLoginPacketListenerImpl.java:221) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]Caused by: java.lang.IllegalStateException: Cannot set lore on AIR	at org.bukkit.inventory.ItemStack.setLore(ItemStack.java:1003) ~[paper-api-26.3.build.142-beta.jar:?]	at com.example.myplugin.LoreListener.onClick(LoreListener.java:18) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:306) ~[paper-api-26.3.build.142-beta.jar:?]	... 6 more

What it means. Air (an empty slot) cannot have a description. The item you tried to change was empty.

Likely causes

event.getCurrentItem() or the item in hand was AIR or null.

How to fix it

Skip empty items:

Java

1ItemStack item = event.getCurrentItem();2if (item == null || item.isEmpty()) {3    return;4}

Read more: Items and ItemStacks, Inventories

IllegalStateException: Already scheduled as N (BukkitRunnable reused)

What you see

[14:12:03 ERROR]: Could not pass event PlayerJoinEvent to MyPlugin v1.0.0org.bukkit.event.EventException: null	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:310) ~[paper-api-26.3.build.142-beta.jar:?]Caused by: java.lang.IllegalStateException: Already scheduled as 47	at org.bukkit.scheduler.BukkitRunnable.checkNotYetScheduled(BukkitRunnable.java:162) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.scheduler.BukkitRunnable.runTaskTimer(BukkitRunnable.java:117) ~[paper-api-26.3.build.142-beta.jar:?]	at com.example.myplugin.JoinListener.onJoin(JoinListener.java:19) ~[my-plugin-1.0.0.jar:?]	... 6 more

What it means. A BukkitRunnable object can be scheduled only once. You tried to start the same object again while it was already running.

Likely causes

The runnable is stored in a field and runTaskTimer is called on it for every player.

How to fix it

Create a new runnable each time:

Java

1new BukkitRunnable() {2    @Override3    public void run() {4        player.sendRichMessage("Tick");5    }6}.runTaskTimer(plugin, 0L, 20L);

Or use the lambda form scheduler.runTaskTimer(plugin, task -> { ... }, 0L, 20L), which creates a fresh task every call.

ConcurrentModificationException (removing from a list while looping)

What you see

[14:03:40 ERROR]: Could not pass event PlayerQuitEvent to MyPlugin v1.0.0org.bukkit.event.EventException: null	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:310) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.plugin.RegisteredListener.callEvent(RegisteredListener.java:71) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperEventManager.callEvent(PaperEventManager.java:54) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.callEvent(PaperPluginManagerImpl.java:131) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.callEvent(SimplePluginManager.java:628) ~[paper-api-26.3.build.142-beta.jar:?]	at net.minecraft.server.players.PlayerList.placeNewPlayer(PlayerList.java:342) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.network.ServerLoginPacketListenerImpl.placeNewPlayer(ServerLoginPacketListenerImpl.java:221) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]Caused by: java.util.ConcurrentModificationException	at java.base/java.util.ArrayList$Itr.checkForComodification(ArrayList.java:1096)	at java.base/java.util.ArrayList$Itr.next(ArrayList.java:1050)	at com.example.myplugin.PartyManager.kickOffline(PartyManager.java:36) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:306) ~[paper-api-26.3.build.142-beta.jar:?]	... 6 more

What it means. You changed a list (added or removed items) while a loop was still walking through it. Java detects this and stops, because the loop would lose its place.

Likely causes

list.remove(item) inside a for-each loop over the same list.
Another thread changed the list at the same time.

How to fix it

Use removeIf:

Java

1players.removeIf(name -> name.startsWith("S"));

Or loop over a copy:

Java

1for (String name : new ArrayList<>(players)) {2    if (name.startsWith("S")) {3        players.remove(name);4    }5}

If several threads use the list, use ConcurrentHashMap or CopyOnWriteArrayList.

StackOverflowError (a method calls itself forever)

What you see

[14:03:40 ERROR]: Could not pass event PlayerJoinEvent to MyPlugin v1.0.0org.bukkit.event.EventException: null	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:310) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.plugin.RegisteredListener.callEvent(RegisteredListener.java:71) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperEventManager.callEvent(PaperEventManager.java:54) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.callEvent(PaperPluginManagerImpl.java:131) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.callEvent(SimplePluginManager.java:628) ~[paper-api-26.3.build.142-beta.jar:?]	at net.minecraft.server.players.PlayerList.placeNewPlayer(PlayerList.java:342) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.network.ServerLoginPacketListenerImpl.placeNewPlayer(ServerLoginPacketListenerImpl.java:221) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]Caused by: java.lang.StackOverflowError	at com.example.myplugin.Counter.countdown(Counter.java:9) ~[my-plugin-1.0.0.jar:?]	at com.example.myplugin.Counter.countdown(Counter.java:9) ~[my-plugin-1.0.0.jar:?]	at com.example.myplugin.Counter.countdown(Counter.java:9) ~[my-plugin-1.0.0.jar:?]	at com.example.myplugin.Counter.countdown(Counter.java:9) ~[my-plugin-1.0.0.jar:?]	at com.example.myplugin.Counter.countdown(Counter.java:9) ~[my-plugin-1.0.0.jar:?]	at com.example.myplugin.Counter.countdown(Counter.java:9) ~[my-plugin-1.0.0.jar:?]	at com.example.myplugin.Counter.countdown(Counter.java:9) ~[my-plugin-1.0.0.jar:?]	at com.example.myplugin.Counter.countdown(Counter.java:9) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:306) ~[paper-api-26.3.build.142-beta.jar:?]	... 6 more

What it means. A method called itself again and again with no end, until Java ran out of room to remember all the calls. The same line appears hundreds of times in the trace.

Likely causes

A recursive method without a stopping case.
Two methods that call each other forever.
A getter that calls itself, or an event handler that triggers the same event again (for example teleporting in a teleport event).

How to fix it

Look at the repeated line in the trace: that method is calling itself.

Add a stopping case at the top:

Java

1static int countdown(int n) {2    if (n <= 0) {3        return 0;4    }5    return countdown(n - 1) + 1;6}

If an event handler causes the same event, check a flag or compare locations before acting.

ArithmeticException: / by zero

What you see

[14:03:40 ERROR]: Could not pass event PlayerDeathEvent to MyPlugin v1.0.0org.bukkit.event.EventException: null	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:310) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.plugin.RegisteredListener.callEvent(RegisteredListener.java:71) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperEventManager.callEvent(PaperEventManager.java:54) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.callEvent(PaperPluginManagerImpl.java:131) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.callEvent(SimplePluginManager.java:628) ~[paper-api-26.3.build.142-beta.jar:?]	at net.minecraft.server.players.PlayerList.placeNewPlayer(PlayerList.java:342) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.network.ServerLoginPacketListenerImpl.placeNewPlayer(ServerLoginPacketListenerImpl.java:221) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]Caused by: java.lang.ArithmeticException: / by zero	at com.example.myplugin.StatsListener.onDeath(StatsListener.java:24) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:306) ~[paper-api-26.3.build.142-beta.jar:?]	... 6 more

What it means. Your code divided a whole number by zero. Java cannot do that with int or long.

Likely causes

Kills divided by deaths when there are no deaths yet.
An average of an empty list.

How to fix it

Check for zero first:

Java

1double ratio = deaths == 0 ? kills : (double) kills / deaths;

Dividing double numbers by zero does not crash but gives Infinity or NaN, which is also not what you want.

Read more: Operators and math

UnsupportedOperationException (changing an immutable list)

What you see

[14:03:40 ERROR]: Could not pass event PlayerJoinEvent to MyPlugin v1.0.0org.bukkit.event.EventException: null	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:310) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.plugin.RegisteredListener.callEvent(RegisteredListener.java:71) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperEventManager.callEvent(PaperEventManager.java:54) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.callEvent(PaperPluginManagerImpl.java:131) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.callEvent(SimplePluginManager.java:628) ~[paper-api-26.3.build.142-beta.jar:?]	at net.minecraft.server.players.PlayerList.placeNewPlayer(PlayerList.java:342) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.network.ServerLoginPacketListenerImpl.placeNewPlayer(ServerLoginPacketListenerImpl.java:221) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]Caused by: java.lang.UnsupportedOperationException	at java.base/java.util.ImmutableCollections.uoe(ImmutableCollections.java:159)	at java.base/java.util.ImmutableCollections$AbstractImmutableCollection.add(ImmutableCollections.java:164)	at com.example.myplugin.RankManager.addRank(RankManager.java:18) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:306) ~[paper-api-26.3.build.142-beta.jar:?]	... 6 more

What it means. List.of(...), Map.of(...) and some methods that return lists give you a list that cannot be changed. Calling add or remove on it throws this exception.

Likely causes

A list made with List.of(...) or stream().toList() and then changed.
A list that an API method returned.

How to fix it

Make a copy that can be changed:

Java

1List<String> ranks = new ArrayList<>(List.of("member", "vip"));2ranks.add("admin");

Read more: Lists, sets and maps

OutOfMemoryError: Java heap space (server or program out of memory)

What you see

[14:25:51 ERROR]: Exception in thread "Server thread"java.lang.OutOfMemoryError: Java heap space	at java.base/java.util.Arrays.copyOf(Arrays.java:3482) ~[?:?]	at java.base/java.util.ArrayList.grow(ArrayList.java:237) ~[?:?]	at com.example.myplugin.BlockLogger.record(BlockLogger.java:21) ~[my-plugin-1.0.0.jar:?]	at com.example.myplugin.BlockLogger.onBreak(BlockLogger.java:14) ~[my-plugin-1.0.0.jar:?]

What it means. Java used all the memory it is allowed to use. The part of the trace in your own code shows what was growing.

Likely causes

A list or map that only ever gets bigger (a log of every block break, never cleared).
A server started with too little memory (-Xmx512M).
Reading a whole huge file into memory.

How to fix it

Find your own code in the trace and check what it keeps adding to.
Remove old entries, or write them to a file or database instead of keeping them in memory.
Give the server more memory only after checking your code: -Xms4G -Xmx4G in the start command.
Remove entries when players leave (PlayerQuitEvent) so the data does not pile up.

Error: Could not find or load main class (running a class that has no main)

What you see

Error: Could not find or load main class MianCaused by: java.lang.ClassNotFoundException: Mian

What it means. Java was asked to start a class by name and could not find it. This happens when you run the wrong thing: a plugin is not started with a main method, the server starts it.

Likely causes

A typo in the class name in the run configuration.
The project has not been built yet, so there are no compiled classes.
You tried to run a plugin class from IntelliJ's normal Run button.

How to fix it

Plugins run inside the Paper server. Use the Run Paper Server configuration (Gradle runServer) instead of running a class.
For a plain Java program, build the project first and check that the class name matches exactly.

Main method not found in class (running a plugin class like a program)

What you see

Error: Main method not found in class com.example.myplugin.MyPlugin, please define the main method as:   public static void main(String[] args)or a JavaFX application class must extend javafx.application.Application

What it means. You pressed the green Run arrow on a class that is not a program. A plugin class has onEnable, not main: the server calls it, not you.

Likely causes

IntelliJ made a run configuration for your plugin class.
You pressed Run while the plugin class was open.

How to fix it

Delete that run configuration and pick Run Paper Server from the list next to the green arrow.
Only classes with void main() can be run alone.

NoSuchMethodError / IncompatibleClassChangeError (plugin built for another Paper version)

What you see

[14:02:12 ERROR]: Error occurred while enabling OldPlugin v2.1 (Is it up to date?)java.lang.NoSuchMethodError: 'org.bukkit.entity.Player[] org.bukkit.Server.getOnlinePlayers()'	at com.oldauthor.oldplugin.Broadcaster.sendAll(Broadcaster.java:42) ~[OldPlugin-2.1.jar:?]	at com.oldauthor.oldplugin.OldPlugin.onEnable(OldPlugin.java:25) ~[OldPlugin-2.1.jar:?]	at org.bukkit.plugin.java.JavaPlugin.setEnabled(JavaPlugin.java:285) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperPluginInstanceManager.enablePlugin(PaperPluginInstanceManager.java:200) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.enablePlugin(PaperPluginManagerImpl.java:104) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.enablePlugin(SimplePluginManager.java:507) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.craftbukkit.CraftServer.enablePlugin(CraftServer.java:560) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.craftbukkit.CraftServer.enablePlugins(CraftServer.java:493) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.MinecraftServer.loadWorld0(MinecraftServer.java:589) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]

What it means. The plugin was compiled against an older Paper API where this method looked different. The method it needs does not exist (any more) in the server that is running it.

Likely causes

A plugin made for an older Minecraft version on a newer server.
Your own plugin compiled against an older API than the server, or the other way round.

How to fix it

Download a newer version of that plugin (look for one that supports Paper 26.3).
For your own plugin: compile against paper-api:26.3.build.142-beta (Gradle paperVersion) and rebuild.
If the plugin is abandoned, look for a maintained alternative.

NoSuchFieldError: GENERIC_MAX_HEALTH and other renamed constants

What you see

[14:02:12 ERROR]: Error occurred while enabling OldPlugin v2.1 (Is it up to date?)java.lang.NoSuchFieldError: Class org.bukkit.attribute.Attribute does not have member field 'org.bukkit.attribute.Attribute GENERIC_MAX_HEALTH'	at com.oldauthor.oldplugin.Health.boost(Health.java:30) ~[OldPlugin-2.1.jar:?]	at com.oldauthor.oldplugin.OldPlugin.onEnable(OldPlugin.java:22) ~[OldPlugin-2.1.jar:?]	at org.bukkit.plugin.java.JavaPlugin.setEnabled(JavaPlugin.java:285) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperPluginInstanceManager.enablePlugin(PaperPluginInstanceManager.java:200) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.enablePlugin(PaperPluginManagerImpl.java:104) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.enablePlugin(SimplePluginManager.java:507) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.craftbukkit.CraftServer.enablePlugin(CraftServer.java:560) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.craftbukkit.CraftServer.enablePlugins(CraftServer.java:493) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.MinecraftServer.loadWorld0(MinecraftServer.java:589) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]

What it means. A constant that the plugin expects (Attribute.GENERIC_MAX_HEALTH) does not exist in this Paper version. Paper renamed it to Attribute.MAX_HEALTH.

Likely causes

A plugin compiled for an older Minecraft version.
Your own code copied from an old tutorial and not recompiled after updating Paper.

How to fix it

In your own code use the new name and rebuild:

Java

1player.getAttribute(Attribute.MAX_HEALTH).setBaseValue(40.0);

For somebody else's plugin: update it to a version for Paper 26.3.
Compare old and new names with the Names Lookup tool.

IllegalPluginAccessException: plugin attempted to register while disabled

What you see

[14:30:41 ERROR]: Error occurred while disabling MyPlugin v1.0.0org.bukkit.plugin.IllegalPluginAccessException: Plugin attempted to register task while disabled	at org.bukkit.craftbukkit.scheduler.CraftScheduler.validate(CraftScheduler.java:612) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.craftbukkit.scheduler.CraftScheduler.runTask(CraftScheduler.java:180) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at com.example.myplugin.MyPlugin.onDisable(MyPlugin.java:34) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPlugin.setEnabled(JavaPlugin.java:285) ~[paper-api-26.3.build.142-beta.jar:?]

What it means. Paper does not let a plugin schedule new tasks or register listeners once it is switched off. Your code tried exactly that, usually in onDisable, or from a task that was still running.

Likely causes

A task scheduled in onDisable (saving data later).
A repeating task or async callback that fires after the plugin was disabled and schedules something new.

How to fix it

In onDisable do the work right now, on the same thread, instead of scheduling it.

Save data directly:

Java

1@Override2public void onDisable() {3    saveAllNow();4}

Cancel your own tasks in onDisable: getServer().getScheduler().cancelTasks(this);.
Check isEnabled() at the start of callbacks that might run late.

Could not pass event X to Y (an error inside an event handler)

What you see

[14:03:40 ERROR]: Could not pass event InventoryClickEvent to MyPlugin v1.0.0org.bukkit.event.EventException: null	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:310) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.plugin.RegisteredListener.callEvent(RegisteredListener.java:71) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperEventManager.callEvent(PaperEventManager.java:54) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.callEvent(PaperPluginManagerImpl.java:131) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.callEvent(SimplePluginManager.java:628) ~[paper-api-26.3.build.142-beta.jar:?]	at net.minecraft.server.players.PlayerList.placeNewPlayer(PlayerList.java:342) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.network.ServerLoginPacketListenerImpl.placeNewPlayer(ServerLoginPacketListenerImpl.java:221) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]Caused by: com.example.myplugin.ShopClosedException: The shop is closed for the night	at com.example.myplugin.ShopListener.onClick(ShopListener.java:33) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:306) ~[paper-api-26.3.build.142-beta.jar:?]	... 6 more

What it means. Your event handler (a method with @EventHandler) threw an exception. Paper catches it, prints this message and carries on, so the server does not crash, but your handler stopped halfway.

Likely causes

Any exception inside the handler. The real reason is the Caused by: line.

How to fix it

Read the Caused by: line. That is the real error: look it up here.
The message names the event (InventoryClickEvent) and your plugin (MyPlugin v1.0.0).
Find the first line that names your own package: it shows the file and line to fix.

Unhandled exception executing command (an error inside a command)

What you see

[14:05:09 ERROR]: nullorg.bukkit.command.CommandException: Unhandled exception executing command 'shop' in plugin MyPlugin v1.0.0	at org.bukkit.command.PluginCommand.execute(PluginCommand.java:47) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.command.SimpleCommandMap.dispatch(SimpleCommandMap.java:152) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.craftbukkit.CraftServer.dispatchCommand(CraftServer.java:1034) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.commands.Commands.performCommand(Commands.java:301) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]Caused by: com.example.myplugin.ShopClosedException: The shop is closed for the night	at com.example.myplugin.ShopCommand.onCommand(ShopCommand.java:27) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.command.PluginCommand.execute(PluginCommand.java:43) ~[paper-api-26.3.build.142-beta.jar:?]	... 3 more

What it means. Your command code threw an exception. The player sees "An internal error occurred while attempting to perform this command", and the console shows this trace.

Likely causes

Any exception inside your command's onCommand or execute method.

How to fix it

Read the Caused by: line: it is the real error.
Find the first line with your package name to see the file and line number.
Test the command with no arguments, wrong arguments and from the console.

You need to agree to the EULA in order to run the server

What you see

[14:00:03 INFO]: Loading properties[14:00:03 INFO]: This server is running Paper version 26.3-142-main@4f2a9c1 (Implementing API version 26.3.build.142-beta)[14:00:04 INFO]: You need to agree to the EULA in order to run the server. Go to eula.txt for more info.

What it means. Minecraft servers only start after you accept Mojang's license (the EULA) in a file called eula.txt.

Likely causes

This is the first start of a new server folder.

How to fix it

Open eula.txt in the server folder and change eula=false to eula=true.
Read the EULA at the link inside the file; accepting it is your decision.
Start the server again.
With run-paper in this guide's projects the run configuration already passes -Dcom.mojang.eula.agree=true.

FAILED TO BIND TO PORT (another server is already running)

What you see

[14:00:09 ERROR]: **** FAILED TO BIND TO PORT![14:00:09 ERROR]: The exception was: java.net.BindException: Address already in use: bind[14:00:09 ERROR]: Perhaps a server is already running on that port?

What it means. Two programs cannot listen on the same network port. Port 25565 is already used, most likely by another copy of the server.

Likely causes

A server from an earlier run is still running in the background.
Two projects started at the same time.
Another program uses port 25565.

How to fix it

Stop the other server: type stop in its console, or press the red square in IntelliJ.
Open Task Manager and end leftover java.exe processes that belong to old servers.
Or choose a different port in server.properties:
gradle.properties
```
1server-port=25566
```

Threading and lag errors

Using the game from the wrong thread, and slow code that makes the server lag.

IllegalStateException: Asynchronous ... ! (Bukkit API used off the main thread)

What you see

[14:06:02 ERROR]: Exception in thread "Craft Scheduler Thread - 3 - MyPlugin"java.lang.IllegalStateException: Asynchronous entity add!	at org.spigotmc.AsyncCatcher.catchOp(AsyncCatcher.java:15) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.craftbukkit.CraftWorld.spawn(CraftWorld.java:1451) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at com.example.myplugin.MobWave.spawnWave(MobWave.java:31) ~[my-plugin-1.0.0.jar:?]	at com.example.myplugin.MobWave.lambda$start$0(MobWave.java:18) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.craftbukkit.scheduler.CraftTask.run(CraftTask.java:78) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.craftbukkit.scheduler.CraftAsyncTask.run(CraftAsyncTask.java:57) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1144) ~[?:?]

What it means. The game world may only be changed from the main server thread. Your code ran on a helper thread (an asynchronous task) and touched the world. After "Asynchronous" the message names what you tried: entity add, block change, teleport and so on.

Likely causes

runTaskAsynchronously, runTaskTimerAsynchronously or CompletableFuture code that spawns mobs, edits blocks, teleports players or changes inventories.
A web request or database callback that goes on to use the Bukkit API directly.

How to fix it

Find your own line in the trace (MobWave.spawnWave). Check how it was started: if the trace has CraftAsyncTask, it runs async.

Do the slow work async, then hop back to the main thread for the world change:

Java

1getServer().getScheduler().runTaskAsynchronously(plugin, () -> {2    List<String> names = loadNamesFromDatabase();3    getServer().getScheduler().runTask(plugin, () -> spawnMobs(names));4});

If nothing needs to be slow, use plain runTask instead of the async version.

failed main thread check: Cannot read/write world asynchronously

What you see

[14:06:40 ERROR]: Exception in thread "Craft Scheduler Thread - 1 - MyPlugin"java.lang.IllegalStateException: Thread Thread[#68,Craft Scheduler Thread - 1 - MyPlugin,5,Craft Scheduler Thread - MyPlugin] failed main thread check: Cannot read world asynchronously	at io.papermc.paper.util.TickThread.ensureTickThread(TickThread.java:50) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.world.level.Level.getBlockState(Level.java:781) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at com.example.myplugin.BlockScanner.scan(BlockScanner.java:24) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.craftbukkit.scheduler.CraftAsyncTask.run(CraftAsyncTask.java:57) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]

What it means. Paper checked which thread called it and refused: reading or changing the world is only allowed from the thread that runs the game ticks.

Likely causes

Reading blocks, entities or players inside an async task.
On Folia: using the wrong scheduler for the region that owns that location.

How to fix it

Move the world access into a normal (synchronous) task: getServer().getScheduler().runTask(plugin, ...).
Copy the data you need on the main thread first, then work with the copy in the async task.
On Folia use the region scheduler for that location instead of the global one.

Event may only be triggered synchronously / cannot be triggered asynchronously

What you see

[14:07:11 ERROR]: Exception in thread "Craft Scheduler Thread - 2 - MyPlugin"java.lang.IllegalStateException: CustomShopEvent cannot be triggered asynchronously from another thread.	at org.bukkit.plugin.SimplePluginManager.callEvent(SimplePluginManager.java:637) ~[paper-api-26.3.build.142-beta.jar:?]	at com.example.myplugin.ShopService.buy(ShopService.java:44) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.craftbukkit.scheduler.CraftAsyncTask.run(CraftAsyncTask.java:57) ~[paper-26.3.build.142-beta.jar:?]

What it means. You called an event (callEvent) from a helper thread. Normal events must be called on the main server thread. Only events created as asynchronous (like AsyncChatEvent) may be called elsewhere.

Likely causes

getPluginManager().callEvent(...) inside an async task.
A custom event created without the isAsync flag but used from an async thread.

How to fix it

Switch to the main thread before calling the event:

Java

1getServer().getScheduler().runTask(plugin, () -> {2    getServer().getPluginManager().callEvent(new CustomShopEvent(player));3});

If the event really happens off-thread, create it with the async flag: super(true) in its constructor.

Can't keep up! Is the server overloaded?

What you see

[14:09:20 WARN]: Can't keep up! Is the server overloaded? Running 5123ms or 102 ticks behind

What it means. The server must finish a tick (one game step) every 50 ms. This message says it fell behind by several seconds, so players see lag.

Likely causes

Slow code on the main thread: a database call, file access, web request or Thread.sleep.
A heavy loop (scanning many blocks) that runs in one tick.
A busy world with many entities, or a server with too little CPU.

How to fix it

Move slow work (files, databases, web) to async tasks and hop back to the main thread for results.
Never call Thread.sleep in plugin code.
Spread large jobs over many ticks.
Run /spark profiler (the spark plugin) to see which plugin takes the time.

The server has stopped responding (watchdog)

What you see

[14:15:44 ERROR]: --- DO NOT REPORT THIS TO PAPER - THIS IS NOT A BUG OR A CRASH  - 26.3-142-main@4f2a9c1 ---[14:15:44 ERROR]: The server has not responded for 10 seconds! Creating thread dump[14:15:44 ERROR]: ------------------------------[14:15:44 ERROR]: Server thread dump (Look for plugins here before reporting to Paper!):[14:15:44 ERROR]: Current Thread: Server thread[14:15:44 ERROR]: 	PID: 41 | Suspended: false | Native: false | State: TIMED_WAITING[14:15:44 ERROR]: 	Stack:[14:15:44 ERROR]: 		java.base@25.0.4/java.lang.Thread.sleep0(Native Method)[14:15:44 ERROR]: 		com.example.myplugin.SlowTask.run(SlowTask.java:19)

What it means. The main thread did not finish its work for many seconds, so Paper's watchdog printed what the thread was doing. The first lines with your own package name show the slow code.

Likely causes

Thread.sleep, a web request, a database query or a file read on the main thread.
An endless loop (while (true) without a way out).

How to fix it

Look in the thread dump for the first line with your package name: that is the code that blocked.
Move the slow work to an async task.
Check every while loop has a condition that eventually becomes false.

YAML errors

Mistakes in plugin.yml, config.yml and other YAML files.

YAML: found character TAB that cannot start any token

What you see

[14:02:09 ERROR]: Could not load 'plugins/my-plugin-1.0.0.jar' in folder 'plugins'org.bukkit.plugin.InvalidPluginException: org.bukkit.plugin.InvalidDescriptionException: Invalid plugin.yml	at io.papermc.paper.plugin.provider.type.spigot.SpigotPluginProvider.createInstance(SpigotPluginProvider.java:141) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.provider.type.spigot.SpigotPluginProvider.createInstance(SpigotPluginProvider.java:36) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	... 7 moreCaused by: org.bukkit.plugin.InvalidDescriptionException: Invalid plugin.yml	at org.bukkit.plugin.PluginDescriptionFile.<init>(PluginDescriptionFile.java:120) ~[paper-api-26.3.build.142-beta.jar:?]	... 9 moreCaused by: while scanning for the next tokenfound character '\t(TAB)' that cannot start any token. (Do not use \t(TAB) for indentation) in 'reader', line 5, column 1:    	heal:    ^	at org.yaml.snakeyaml.scanner.ScannerImpl.fetchMoreTokens(ScannerImpl.java:445) ~[snakeyaml-2.2.jar:?]	... 10 more

What it means. YAML (the format of plugin.yml and config.yml) does not allow the Tab key for indentation. The line named in the message starts with a tab character.

Likely causes

You pressed Tab to indent a line in a YAML file.
You pasted text that contained tab characters.

How to fix it

Delete the tab at the start of the line named in the message (line and column are in the message) and use spaces instead. Two spaces per level is the usual style.
In IntelliJ press Ctrl+Alt+L to reformat: it converts tabs to spaces in YAML.
Turn on View > Active Editor > Show Whitespaces to see tabs.

Read more: plugin.yml explained, Configuration files

YAML: mapping values are not allowed here

What you see

[14:10:22 ERROR]: Cannot load plugins\MyPlugin\config.ymlorg.bukkit.configuration.InvalidConfigurationException: mapping values are not allowed here in 'reader', line 2, column 17:      welcome: Hello: welcome to the server                    ^	at org.bukkit.configuration.file.YamlConfiguration.loadFromString(YamlConfiguration.java:112) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.configuration.file.FileConfiguration.load(FileConfiguration.java:200) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.configuration.file.YamlConfiguration.loadConfiguration(YamlConfiguration.java:174) ~[paper-api-26.3.build.142-beta.jar:?]

What it means. YAML found a second colon in a place where only one is allowed. A colon followed by a space means "this is a key and now comes its value". A value that itself contains : confuses it.

Likely causes

A value with a colon and a space in it (welcome: Hello: welcome).
A line like title: Shop: Main Menu or a time such as Time: 10: 30.

How to fix it

Put quotes around the whole value:

YAML

1messages:2  welcome: "Hello: welcome to the server"

The message says the line and column. The ^ arrow points at the second colon.

Read more: Configuration files, plugin.yml explained

YAML: found character that cannot start any token (%, @, `, {...)

What you see

[14:10:22 ERROR]: Cannot load plugins\MyPlugin\config.ymlorg.bukkit.configuration.InvalidConfigurationException: while scanning for the next tokenfound character '%' that cannot start any token. (Do not use % for indentation) in 'reader', line 2, column 9:      join: %player% joined the game            ^	at org.bukkit.configuration.file.YamlConfiguration.loadFromString(YamlConfiguration.java:112) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.configuration.file.FileConfiguration.load(FileConfiguration.java:200) ~[paper-api-26.3.build.142-beta.jar:?]

What it means. A value starts with a character that YAML keeps for itself, such as %, @, a back tick, {, [, *, & or !. YAML does not know what to do with it, so it stops.

Likely causes

Placeholders like %player% at the start of a value.
A value starting with @, a back tick or & (including old color codes like &aHello).

How to fix it

Put the value in quotes:

YAML

1messages:2  join: "%player% joined the game"3  welcome: "&aWelcome!"

Quotes make YAML read everything inside as plain text.

YAML: expected <block end> (wrong indentation)

What you see

[14:10:22 ERROR]: Cannot load plugins\MyPlugin\config.ymlorg.bukkit.configuration.InvalidConfigurationException: while parsing a block mapping in 'reader', line 2, column 3:      spawn:      ^expected <block end>, but found '<block mapping start>' in 'reader', line 4, column 4:       y: 2       ^	at org.bukkit.configuration.file.YamlConfiguration.loadFromString(YamlConfiguration.java:112) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.configuration.file.FileConfiguration.load(FileConfiguration.java:200) ~[paper-api-26.3.build.142-beta.jar:?]

What it means. In YAML, indentation (the spaces at the start of a line) shows which key belongs to which section. Two lines that should be on the same level use a different number of spaces.

Likely causes

One line has one space more or fewer than its neighbors (x: 1 has 4, y: 2 has 3).
A mix of tabs and spaces.
Text pasted from a website with different spacing.

How to fix it

Look at the two lines the message names. Keys on the same level must start in the same column.
Use the same number of spaces for siblings:
YAML
```
1homes:2  spawn:3    x: 14    y: 2
```
In IntelliJ reformat the file with Ctrl+Alt+L.

Read more: Configuration files, plugin.yml explained

YAML: while scanning a quoted scalar ... found unexpected end of stream

What you see

[14:10:22 ERROR]: Cannot load plugins\MyPlugin\config.ymlorg.bukkit.configuration.InvalidConfigurationException: while scanning a quoted scalar in 'reader', line 2, column 12:      welcome: 'Welcome to the server               ^found unexpected end of stream in 'reader', line 4, column 1:        ^	at org.bukkit.configuration.file.YamlConfiguration.loadFromString(YamlConfiguration.java:112) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.configuration.file.FileConfiguration.load(FileConfiguration.java:200) ~[paper-api-26.3.build.142-beta.jar:?]

What it means. A text that started with a quote never got its closing quote, so YAML read to the end of the file looking for it.

Likely causes

A missing closing ' or ".
An apostrophe inside single quotes ('Don't do that').

How to fix it

Check the line shown in the message: does the quote at the start have a partner at the end?
To put an apostrophe inside single quotes, double it, or use double quotes:
YAML
```
1messages:2  warn: 'Don''t do that'3  warn2: "Don't do that"
```

Read more: Configuration files

YAML: while parsing a flow sequence (missing ])

What you see

[14:10:22 ERROR]: Cannot load plugins\MyPlugin\config.ymlorg.bukkit.configuration.InvalidConfigurationException: while parsing a flow sequence in 'reader', line 1, column 9:    worlds: [world, world_nether            ^expected ',' or ']', but got : in 'reader', line 2, column 10:    max-homes: 3             ^	at org.bukkit.configuration.file.YamlConfiguration.loadFromString(YamlConfiguration.java:112) ~[paper-api-26.3.build.142-beta.jar:?]

What it means. A list written in square brackets [a, b] (or a map in { }) was never closed.

Likely causes

A missing ] at the end of the list.

How to fix it

Close the bracket, or write the list one item per line:

YAML

1worlds: [world, world_nether]2worlds2:3  - world4  - world_nether

Read more: Configuration files

YAML: while scanning an alias (a value starting with * or &)

What you see

[14:10:22 ERROR]: Cannot load plugins\MyPlugin\config.ymlorg.bukkit.configuration.InvalidConfigurationException: while scanning an alias in 'reader', line 1, column 10:    message: *Welcome* to the server             ^unexpected character found *(42) in 'reader', line 1, column 18:    message: *Welcome* to the server                     ^	at org.bukkit.configuration.file.YamlConfiguration.loadFromString(YamlConfiguration.java:112) ~[paper-api-26.3.build.142-beta.jar:?]

What it means. In YAML a value that starts with * is an alias (a reference to something named earlier) and & starts an anchor. Your text starts with one of them by accident.

Likely causes

A message like *Welcome* or &aWelcome written without quotes.

How to fix it

Quote the value:
YAML
```
1message: "*Welcome* to the server"
```

Read more: Configuration files

Config file errors

Reading and saving config files, and settings that are missing.

Cannot load config.yml (InvalidConfigurationException: Top level is not a Map)

What you see

[14:10:22 ERROR]: Cannot load plugins\MyPlugin\config.ymlorg.bukkit.configuration.InvalidConfigurationException: Top level is not a Map.	at org.bukkit.configuration.file.YamlConfiguration.loadFromString(YamlConfiguration.java:109) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.configuration.file.FileConfiguration.load(FileConfiguration.java:200) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.configuration.file.YamlConfiguration.loadConfiguration(YamlConfiguration.java:174) ~[paper-api-26.3.build.142-beta.jar:?]

What it means. Paper could not read your config file as a list of key: value settings. When it prints this without a line number, the file is empty, only a single text, or only a list.

Likely causes

The file contains just a word or a list (- a) at the top.
A leftover character such as a stray - or text before the first key.

How to fix it

Open the file and check that every line looks like key: value or is indented under a key.
If the message names a line and column, fix that spot (look for the more specific YAML entries here).
When in doubt delete the file: saveDefaultConfig() creates a fresh one.

Read more: Configuration files, plugin.yml explained

The embedded resource 'config.yml' cannot be found

What you see

[14:02:12 ERROR]: Error occurred while enabling MyPlugin v1.0.0 (Is it up to date?)java.lang.IllegalArgumentException: The embedded resource 'config.yml' cannot be found in plugins/my-plugin-1.0.0.jar	at org.bukkit.plugin.java.JavaPlugin.saveResource(JavaPlugin.java:405) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.plugin.java.JavaPlugin.saveDefaultConfig(JavaPlugin.java:394) ~[paper-api-26.3.build.142-beta.jar:?]	at com.example.myplugin.MyPlugin.onEnable(MyPlugin.java:11) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPlugin.setEnabled(JavaPlugin.java:285) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperPluginInstanceManager.enablePlugin(PaperPluginInstanceManager.java:200) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.enablePlugin(PaperPluginManagerImpl.java:104) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.enablePlugin(SimplePluginManager.java:507) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.craftbukkit.CraftServer.enablePlugin(CraftServer.java:560) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.craftbukkit.CraftServer.enablePlugins(CraftServer.java:493) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.MinecraftServer.loadWorld0(MinecraftServer.java:589) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]

What it means. saveDefaultConfig() copies config.yml from inside your jar to the plugin's folder. The file is not inside the jar.

Likely causes

config.yml is not in src/main/resources.
The file is called config.yaml or Config.yml.
You are running an older jar that was built before you added the file.

How to fix it

Create src/main/resources/config.yml (right next to plugin.yml).
Check the exact file name, with a lowercase c and .yml.
Rebuild the plugin and replace the old jar.

Could not save config.yml because it already exists (warning)

What you see

[14:11:02 WARN]: Could not save config.yml to plugins\MyPlugin\config.yml because config.yml already exists.

What it means. You called saveResource("config.yml") and the file is already in the plugin folder. Paper does not overwrite it, and tells you so.

Likely causes

saveResource is called every start, even when the file exists.
Often it appears with saveResource("config.yml", false) on a second run.

How to fix it

Use saveDefaultConfig() for config.yml: it only copies the file when it does not exist, and is silent otherwise.
If you want to overwrite on purpose, call saveResource("config.yml", true).
Or check first: if (!new File(getDataFolder(), "data.yml").exists()) saveResource("data.yml", false);.

Read more: Configuration files

Could not save config to file (IOException)

What you see

[14:12:58 ERROR]: Could not save config to plugins\MyPlugin\config.ymljava.nio.file.AccessDeniedException: plugins\MyPlugin\config.yml	at java.base/sun.nio.fs.WindowsException.translateToIOException(WindowsException.java:89) ~[?:?]	at java.base/sun.nio.fs.WindowsFileSystemProvider.newByteChannel(WindowsFileSystemProvider.java:236) ~[?:?]	at org.bukkit.configuration.file.YamlConfiguration.save(YamlConfiguration.java:87) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.plugin.java.JavaPlugin.saveConfig(JavaPlugin.java:150) ~[paper-api-26.3.build.142-beta.jar:?]

What it means. The server tried to write a file and the operating system refused, or the folder does not exist.

Likely causes

The file is open in another program (Notepad, IntelliJ) or locked by antivirus.
The file or folder is read-only, or the server runs from a protected folder like C:\Program Files.
The disk is full.

How to fix it

Close other programs that have the file open.
Run the server from a normal folder under your user folder, for example C:\Users\<you>\servers\test.
Check free disk space.
Call getDataFolder().mkdirs() before writing your own files.

NullPointerException: getConfigurationSection(...) returned null

What you see

[14:02:12 ERROR]: Error occurred while enabling MyPlugin v1.0.0 (Is it up to date?)java.lang.NullPointerException: Cannot invoke "org.bukkit.configuration.ConfigurationSection.getKeys(boolean)" because the return value of "org.bukkit.configuration.file.FileConfiguration.getConfigurationSection(String)" is null	at com.example.myplugin.Warps.load(Warps.java:22) ~[my-plugin-1.0.0.jar:?]	at com.example.myplugin.MyPlugin.onEnable(MyPlugin.java:13) ~[my-plugin-1.0.0.jar:?]	at org.bukkit.plugin.java.JavaPlugin.setEnabled(JavaPlugin.java:285) ~[paper-api-26.3.build.142-beta.jar:?]	at io.papermc.paper.plugin.manager.PaperPluginInstanceManager.enablePlugin(PaperPluginInstanceManager.java:200) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.enablePlugin(PaperPluginManagerImpl.java:104) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.plugin.SimplePluginManager.enablePlugin(SimplePluginManager.java:507) ~[paper-api-26.3.build.142-beta.jar:?]	at org.bukkit.craftbukkit.CraftServer.enablePlugin(CraftServer.java:560) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at org.bukkit.craftbukkit.CraftServer.enablePlugins(CraftServer.java:493) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]	at net.minecraft.server.MinecraftServer.loadWorld0(MinecraftServer.java:589) ~[paper-26.3.build.142.jar:26.3-142-main@4f2a9c1]

What it means. You asked the config for a section (a group of settings) that is not in the file, and getConfigurationSection returns null in that case.

Likely causes

The warps: section does not exist in config.yml yet (empty file, or the key is spelled differently).
The server has an old config.yml from before you added the section; saveDefaultConfig never overwrites it.
Wrong indentation made the key part of another section.

How to fix it

Check for null before using the section:

Java

1ConfigurationSection warps = getConfig().getConfigurationSection("warps");2if (warps == null) {3    return;4}5warps.getKeys(false).forEach(getLogger()::info);

Delete the old config.yml in the server's plugins/MyPlugin folder so the new default is created, or add the missing section by hand.
Use getConfig().options().copyDefaults(true) plus saveConfig() to add missing keys without deleting.

What players see

Messages and oddities that players report, and what causes them.

Player sees: Unknown or incomplete command

What you see

Unknown or incomplete command, see below for error/heal<--[HERE]

What it means. The server does not know the command the player typed. Players also see this when a command exists but they are not allowed to use it (Paper hides commands without permission).

Likely causes

The plugin that adds the command is not loaded (look for errors at startup).
The command is not in plugin.yml, or it is registered with Brigadier but registration failed.
The player lacks the permission, so the command is hidden.
A typo, or an old command name.

How to fix it

In the server console type plugins: your plugin must be green.
Scroll the startup log for errors from your plugin.
Check that the command is under commands: in plugin.yml (classic) or registered in the COMMANDS lifecycle event (Brigadier).
Try as an operator (op <name>) to rule out a permission problem.

Player sees: I'm sorry, but you do not have permission to perform this command

What you see

I'm sorry, but you do not have permission to perform this command. Please contact the server administrators if you believe that this is a mistake.

What it means. The command exists, but the player does not have the permission that the command needs.

Likely causes

The command has a permission: in plugin.yml and the player was not given it.
The permission name in plugin.yml and in the permissions plugin differ.
The player is not an operator and default: is op.

How to fix it

Check the exact permission name in plugin.yml (myplugin.heal).
Give it with your permissions plugin (for example LuckPerms: /lp user Steve permission set myplugin.heal true).

Or let everyone use it by default:

YAML

1permissions:2  myplugin.heal:3    description: Use /heal4    default: true

Test with op Steve to see if permissions are the problem.

Colors show up as &a, &6 codes in chat

What you see

Players see this in chat: &aWelcome &6to the server&r!

What it means. Minecraft itself does not understand &a. & color codes only work when a plugin translates them. Paper's modern way is MiniMessage tags like <green>.

Likely causes

Using sendMessage("&aHello") with no translation step.
An old tutorial that used ChatColor.translateAlternateColorCodes.
A config file with & codes that the code sends as it is.

How to fix it

Send the message with MiniMessage:

Java

1player.sendRichMessage("<green>Welcome <gold>to the server<reset>!");

If you must keep & codes in a config, convert them:

Java

1Component message = LegacyComponentSerializer.legacyAmpersand().deserialize("&aWelcome &6to the server");2player.sendMessage(message);

Use the MiniMessage Studio to convert old codes.

MiniMessage tags like <green> show up as text

What you see

Players see this in chat: <green>Welcome <gold>to the server

What it means. The text was sent as plain text. Tags like <green> only work if the message goes through MiniMessage.

Likely causes

player.sendMessage("<green>Hi") sends the tags as plain text.
A config value was sent without being parsed.
A tag has a typo, or a \ escaped it.

How to fix it

Use sendRichMessage, or parse yourself:

Java

1player.sendRichMessage("<green>Welcome!");2player.sendMessage(MiniMessage.miniMessage().deserialize(text));

Open the MiniMessage Studio and check that the preview shows colors, not tags.

Color codes show as garbled characters (Â§a)

What you see

Players see: Â§aWelcome Â§6to the server

What it means. The § sign was saved in one text encoding and read in another, so it turned into two odd characters. Minecraft codes use §.

Likely causes

The source file was compiled without UTF-8.
A config file was saved in another encoding (for example by an old Notepad).

How to fix it

Do not write § in code. Use MiniMessage tags (<green>) which are plain ASCII.

Make Gradle compile with UTF-8:

build.gradle.kts

1tasks {2    compileJava {3        options.encoding = Charsets.UTF_8.name()4    }5}

Save config files as UTF-8 (IntelliJ does this by default).

Custom item names and lore appear in italics

What you see

My custom item names and lore show up in italics and I did not ask for that.

What it means. Minecraft draws custom names and lore in italics by default (renamed items look that way). It is not a bug in your plugin.

Likely causes

displayName(...) or lore(...) with a Component that does not say italic is off.

How to fix it

Turn italics off at the start of every line:

Java

1meta.displayName(MiniMessage.miniMessage().deserialize("<!i><gold>Magic Wand"));2meta.lore(List.of(MiniMessage.miniMessage().deserialize("<!i><gray>Right click to cast")));

<!i> means "italic off". The Studio's Item name preview shows the effect.

Player sees: Connection refused / Failed to connect to the server

What you see

Failed to connect to the serverio.netty.channel.AbstractChannel$AnnotatedConnectException: Connection refused: no further information: localhost/127.0.0.1:25565

What it means. Minecraft reached the address, but nothing listens on that port. The server is not running, or the address or port is wrong.

Likely causes

The server is not started yet or has already stopped (look at the console).
The server failed to start because of an error.
A different port than 25565 is used.
A firewall blocks the connection (for other PCs).

How to fix it

Check the server console: it must say Done (…s)! For help, type "help".
On the same PC join with localhost.
If the server uses another port, join with localhost:25566.
For friends on other PCs, forward the port in your router and allow Java in the Windows firewall.

Player sees: Outdated server / Outdated client

What you see

Outdated client! Please use 26.3

What it means. The Minecraft version of the player and of the server do not match. The message says which side needs to update.

Likely causes

The player uses another Minecraft version than the server (Paper 26.3 needs the 26.3 client).

How to fix it

In the Minecraft Launcher create a profile for exactly the version the message names (for example 26.3).
Or update the server (or run an older server) so both match.

Player sees: Internal Exception io.netty.handler.codec.DecoderException

What you see

DisconnectedInternal Exception: io.netty.handler.codec.DecoderException: java.lang.IndexOutOfBoundsException: readerIndex(1) + length(2) exceeds writerIndex(2): UnpooledHeapByteBuf(ridx: 1, widx: 2, cap: 2/2)

What it means. The player's game and the server could not understand each other's data and the connection was closed. It is the player's screen, not a server crash.

Likely causes

A client mod or resource pack that does not match the server.
A plugin sending a broken packet or item (for example a bad custom item).
A different Minecraft version.

How to fix it

Check the server console at the moment of the disconnect: a plugin error is often printed there.
Join with a clean vanilla client without mods.
If it started after a change in your plugin (custom items, GUI titles), undo the change and test again.

Read more: Debugging like a pro, Testing your plugin

Player sees: You are not whitelisted on this server

What you see

You are not whitelisted on this server!

What it means. The server has the whitelist turned on and the player's name is not on it.

Likely causes

white-list=true in server.properties or /whitelist on was used.

How to fix it

In the server console type whitelist add <name>.
Or turn it off with whitelist off while you test.

Read more: Testing your plugin

IntelliJ messages

Warnings and errors that appear in the editor or the Build window.

IntelliJ: Cannot resolve symbol / method

What you see

Cannot resolve symbol 'Player'

What it means. IntelliJ's own checker (red underlines) does not know that name. It is the editor's version of the compiler error cannot find symbol.

Likely causes

The import line is missing.
A typo in the name.
The library is missing or Gradle has not loaded it yet, after you edited the build files.
The Gradle project was not reloaded, or the first import has not finished.

How to fix it

Click the red word and press Alt+Enter, then choose Import class.
If every Paper name is red, open the Gradle tool window and press Reload All Gradle Projects (the circular arrows).
If it stays red, use File > Invalidate Caches > Invalidate and Restart.
Check build.gradle.kts for the Paper dependency and repository.

IntelliJ: Load Gradle Changes (build files edited)

What you see

Gradle build scripts foundLoad Gradle Changes (Ctrl+Shift+O)

What it means. You changed build.gradle.kts, settings.gradle.kts or gradle.properties. IntelliJ shows a small elephant icon in the editor corner until you load the changes. Until then it still uses the old settings.

Likely causes

You edited a build file and did not press the reload button.

How to fix it

Click the elephant icon with the circular arrow in the top right of the editor, or press Ctrl+Shift+O.
Or open the Gradle tool window and press Reload All Gradle Projects.
Wait for the progress bar at the bottom to finish before you build.

IntelliJ: Project JDK is not defined

What you see

Project JDK is not definedSetup JDK

What it means. IntelliJ does not know which Java to use for this project, so it cannot compile or run anything.

Likely causes

No JDK is installed, or none was picked for this project.
The JDK that was chosen was uninstalled.

How to fix it

Click Setup JDK in the yellow bar, or open File > Project Structure > Project.
Under SDK choose your JDK 25. If the list is empty choose Add SDK > Download JDK, select version 25 and vendor Eclipse Temurin.
Also check Settings > Build Tools > Gradle > Gradle JVM.

IntelliJ: Gradle sync failed / Could not run build action

What you see

Gradle sync failed: Could not run build action using Gradle distribution 'https://services.gradle.org/distributions/gradle-9.8.0-bin.zip'.Caused by: java.net.UnknownHostException: services.gradle.org

What it means. IntelliJ asked Gradle to read your project and Gradle failed. The first lines after "Caused by" tell you why.

Likely causes

No internet while Gradle downloaded itself.
A mistake in build.gradle.kts or settings.gradle.kts.
The wrong JDK is set for Gradle.

How to fix it

Open the Build tool window at the bottom and read the lowest error message.
Paste that message into the Error Doctor for a specific explanation.
Check that Gradle JVM (Settings > Build Tools > Gradle) is your JDK 25.
After fixing, press Reload All Gradle Projects.

IntelliJ: Unsupported Java / incompatible Java and Gradle versions

What you see

Unsupported Java.Your build is currently configured to use Java 25.0.4 and Gradle 8.5.Possible solution: - Upgrade Gradle wrapper to 9.8.0 version and re-import the project

What it means. The Java that Gradle runs on and the Gradle version do not fit together. Each Gradle version supports only certain Java versions: Java 25 needs Gradle 9 or newer.

Likely causes

The wrapper points to an old Gradle (like 8.5) but the JDK is 25.
The Gradle JVM is set to a very old or very new JDK.

How to fix it

Use the Gradle from this guide in gradle/wrapper/gradle-wrapper.properties:
gradle.properties
```
1distributionUrl=https\://services.gradle.org/distributions/gradle-9.8.0-bin.zip
```
Or click the "Upgrade Gradle wrapper" link IntelliJ offers.
Set Settings > Build Tools > Gradle > Gradle JVM to JDK 25.

IntelliJ build window: java: release version 25 not supported

What you see

Error:java: error: release version 25 not supported

What it means. IntelliJ is compiling with a JDK older than 25 (or has a project language level of 25 on an older JDK).

Likely causes

The project SDK or the Gradle JVM is JDK 21 or older.
IntelliJ builds with its own compiler setting instead of Gradle.

How to fix it

In File > Project Structure > Project set the SDK to JDK 25 and the language level to 25.
In Settings > Build Tools > Gradle set Build and run using: Gradle and Gradle JVM: JDK 25.
Reload Gradle and rebuild.

IntelliJ: Module SDK is not defined / red Java files

What you see

Module SDK is not definedConfigure Module SDK

What it means. IntelliJ opened the folder but never created a proper Java module with an SDK, so none of the code gets compiled or checked.

Likely causes

You opened the wrong folder (not the project with build.gradle.kts).
The Gradle import never finished.

How to fix it

Close the project and use File > Open on the folder that contains build.gradle.kts. Choose Open as Project and trust the project.
Wait for the Gradle sync to end.
Then set the SDK in File > Project Structure.