Skip to content

Detect plugins accessing the server outside of the main thread - #223

Merged
pavog merged 1 commit into
masterfrom
paper-async-main-thread-check
Nov 17, 2026
Merged

pavog merged 1 commit into
masterfrom
paper-async-main-thread-check

Conversation

@pavog

@pavog pavog commented Nov 17, 2026

Copy link
Copy Markdown
Member
[14:31:39 ERROR]: Thread ChunkWorker failed main thread check: chunk load
java.lang.Throwable
	at org.spigotmc.AsyncCatcher.catchOp(AsyncCatcher.java:9) ~[paper-26.3.jar:26.3-248-0727243]
	at org.bukkit.craftbukkit.CraftWorld.loadChunk(CraftWorld.java:546) ~[paper-26.3.jar:26.3-248-0727243]
	at p32-own-thread-chunk.jar//com.repro.OwnThreadChunkPlugin.lambda$onEnable$0(OwnThreadChunkPlugin.java:15) ~[?:?]

When a plugin does something that is only allowed on the main thread, like loading a chunk or changing a block, from another thread, Paper logs this error and throws IllegalStateException: Asynchronous <action>!.
This was not detected before.

This PR adds MainThreadCheckProblem to the PaperAnalyser, because the message with the thread name is only logged by Paper.
The message names the thread and the action, and the solutions name the plugin:

  • tasks of the Bukkit scheduler run in threads named Craft Scheduler Thread - <n> - <plugin>, so the plugin is known and gets PluginInstallDifferentVersionSolution and PluginRemoveSolution
  • for other threads, the pattern skips the frames of the server and Java in the stack trace and uses the first other class with PluginWithClassInstallDifferentVersionSolution and PluginWithClassRemoveSolution
  • if there is no such class, the error does not come from a plugin and gets no solution

There is only one message for all cases, because the name of a scheduler thread already contains the plugin.
The exception Asynchronous chunk load! that follows is intentionally not matched separately, because it is the same error.

Folia logs the check in another format (Thread failed main thread check: ..., context=thread=...), which is not covered, because there is no real log of it.

Changes

  • add MainThreadCheckProblem
  • add translation for the problem
  • add paper-main-thread-check-block-26-3.log, paper-main-thread-check-chunk-load-26-3.log and paper-main-thread-check-own-thread-26-3.log

@pavog
pavog merged commit 10ae325 into master Nov 17, 2026
3 checks passed
@pavog
pavog deleted the paper-async-main-thread-check branch November 17, 2026 13:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant