Paper Plugin Guide
File mode0

Tools

Error Doctor

Paste a console error, stack trace or build failure and get a diagnosis and a fix.

BeginnerTool

Paste a console error, a stack trace or a Gradle failure. The Error Doctor tells you what it means in plain English, which line of your own code to look at, and how to fix it.

Paste your error

Copy the red text from the console or from IntelliJ's Run or Build window, paste it into the box and press Diagnose. Nothing is sent anywhere: the Doctor runs in your browser and works without internet.

The Error Doctor is loading. If this message stays, JavaScript is turned off in your browser.

What you can paste

  • A Paper server log. Lines like [14:03:40 ERROR]: Could not pass event PlayerJoinEvent to MyPlugin and the lines under them.
  • A stack trace. The list of lines that start with at, together with the Caused by: lines. Paste all of it, not only the first line.
  • Compiler errors. Lines like JoinListener.java:12: error: cannot find symbol, from IntelliJ's Build window or from Gradle.
  • A Gradle failure. Everything from FAILURE: Build failed with an exception down to BUILD FAILED.
  • A YAML or config error. Messages that mention in 'reader', line 3, column 1.
  • What a player sees. For example Unknown or incomplete command, or a short description such as "colors show as &a".
Select the red text in the Run window, press Ctrl+C, then paste it into the Error Doctor

How the Doctor reads an error

Reading a stack trace A stack trace has an exception type and message, then frames from where it broke back to who called it. The first frame in your own plugin shows the file and line. A Caused by line names the original problem. java.lang.IllegalStateException: Backpack data was not loaded yet 1     at com.example.backpack.BackpackManager.open(BackpackManager.java:42) 2     at com.example.backpack.BackpackCommand.onCommand(BackpackCommand.java:19) 3     at org.bukkit.command.PluginCommand.execute(PluginCommand.java:45) 4     ... Caused by: java.io.FileNotFoundException: plugins/Backpack/data.yml 5     at java.base/java.io.FileInputStream.open0(Native Method) 1 Exception type, then the message after the colon: what went wrong. 2 The first frame in your plugin: the file and line to open (line 42). 3 The next frames show who called that line, going back in time. 4 Frames inside Paper or Java: usually not the bug, skim past them. 5 Caused by: the original problem. Fix this one first. Read from the top: the first line is the problem, the first plugin frame is the place.
The parts of an exception report that the Doctor looks for

  1. It finds the exception chain

    It lists the main exception, its message and every Caused by below it. The last one in the chain is usually the real reason.

  2. It finds your code

    It skips every line that belongs to Java, Paper, Minecraft or other libraries and shows the first line from your own plugin, such as Your code: JoinListener.java line 42, in onJoin. That is the place to open first.

  3. It lists compiler errors one by one

    For compiler output you get a table with the file, the line and a plain explanation for each error. Fix the first error first: later ones are often just follow-ups.

  4. It compares with known problems

    Over a hundred common beginner problems are stored with real samples. The Doctor ranks them by how specific the match is and shows the best one first, with the exact lines that matched.

Reading the answer

  • Best match is the problem that fits your text most closely. Also possible are other candidates: read their "What matched" part to decide.
  • What matched shows your own lines with the matching words highlighted. If the highlighted part is not what you expected, try the next card.
  • How to fix it is a numbered list. Try the steps in order and rebuild after each one.
  • Every card links to the chapters that teach the idea behind the problem.

Asking for help with an error

When you ask a person or an AI assistant for help, copy the whole error from its first line to the last Caused by, add the file and line the Doctor found under "Your code", and say what you changed just before it started. That is usually enough to get a useful answer.

Mistakes beginners make with errors

  • Reading only the last line. The cause is in the first error, or in the last Caused by.
  • Fixing the second error first. A single missing bracket can create ten compiler errors. Fix the first one and build again.
  • Pasting only part of the trace. A cut-off trace loses the line of your code.
  • Running an old jar. If the same error appears after you fixed it, rebuild and replace the jar in the plugins folder.