More verbose entity context checks - #306
Open
Dueris wants to merge 4 commits into
Open
Conversation
Toffikk
approved these changes
Jul 29, 2026
BaconCat1
suggested changes
Jul 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
For basically all of Folia's lifetime, one major flaw has been that it can have some errors that are completely undebuggable to the point of insanity. Some examples are shown below as to just how stupid these errors are, and how they have nearly NOTHING to do with the actual error in question. Some of these errors are so obscure, it's just insane. They also RARELY mention plugins in the stacktrace or the error message, meaning finding the causing plugin is extremely difficult. As such, Ive been working the last while on trying to find some way to debug these issues as best as possible to decipher many of the more common issues plugins inflict when improperly doing things in Folia, making debugging plugin issues significantly faster and easier for both server owners and developers and ourselves.
The main thing that was added is the introduction of "region transfer states." These states essentially hold on to several important pieces of data determining what is happening with the region transfer and most importantly, why. This is always set on teleports and portals of any kind, including sync-region teleports too. The information provided by these states is as such:
api_teleport_call,generic_teleport, etc)StackTraceElementobjects captured at the time of creating the transfer state, which can show what is triggering the teleport or portal, whether that be a plugin or notJavaPlugininstance of the first plugin caller found in the stack walker. This can be EXTREMELY useful for finding the plugin that causes these sorts of issuesThese states are placed and removed at the start and end of teleports and portals to ensure the full lifecycle is captured. However, the states are removed before the teleport/portal callbacks(and respective post events) are called, since those can trigger their own teleports and stuff, which would throw an ISE since a state is already placed.
The thread context checks provided by Folia/Paper have been modified to include this data now, which does make them a lot more verbose, but I think we can all agree verbosity is preferred over undebuggable...
There are also places where
try/catchstatements have been placed to catch common areas that misc plugin issues will cause to throw(in undebuggable ways), to try and help debug those areas too.This also changes our world shutdown thread a bit, making it use these states rather than our 2 wonky fields we had before... This also changes how we block if a player is not yet removed from the world but is being removed from the world, making it so it just parks for 1ms in a loop until the player is removed(we shouldnt pass 1 iteration TBH), of which then we teleport the player BACK to the origin(read from the transfer state) location on the world shutdown thread.
Here are some examples of what errors looked like before these changes. We will even play a fun game! If you can guess what the issue is caused by without looking at the code to recreate the issue(included at the very bottom), I will give u a thumbsup reaction(I know super special, right)!! No cheatinggg!!!
1st stack before:
2nd stack before(the initial issue that this was tested with didn't have this thread check, so that's why this 2nd one exists. It's the same thing just without the thread check):
Ok, now that you have def read these stacktraces, put your guesses in!! If you win you get 1 thumbsup emoji!! SUPER special amirite???!!
Yeah so this is caused by a plugin teleporting the player during the
EntityDamageEvent. Yeah I bet none of you saw that one coming. The code:Ignore the location, this was just to simulate the initial issue that I was sent in DMs a long while ago(they figured out the issue after a tiny bit, so very good 🎊). Here are the stacktraces after my changes:
1st stack after:
2nd stack:
The 2nd stack unfortunetly does not include the extra debug in the crash report, given this kind of crash we need special handling for since it doesnt use an entity context check. The extra debug information is logged to console though(obviously). There is also a similar special check added in
RegionizedWorldData#cleanupConnectionsince that is also a path that causes undiagnosable errors too. The extra debug information is provided whenever an entity thread check is thrown and in(at the time of writing) those 2 specific handlings. Most of the extra debug beyond the region transfer state is already existing in Folia under theEntityUtilclassOverall this is aimed to create a framework where we can easily debug current issues and further issues with plugins in the future, since obviously this wont cover EVERYTHING now, but this does cover a significant portion of issues we already see when encountered with plugin-induced exceptions.