How to solve the "Circular dependencies detected!" error
A few days ago, the PaperMC Team released a new plugin loading system. Some server owners running these newer Paper builds (and possibly forks, too) have started encountering the following error while starting up their server:
But what does this really mean?
As the error may suggest, a circular dependency happens whenever a plugin depends on another, that also depends on the first plugin. I know this may sound confusing, so here's a better example:
We have two plugins in our server, CoolLobbyPlugin and CoolCore. CoolLobbyPlugin depends on CoolCore, this is entirely normal and is supported by Paper's new plugin loading system. However, CoolCore also depends on CoolLobbyPlugin, creating a circular dependency, which is unsupported.
Plugin dependency loops like this have been a problem causer for over a decade, regularly breaking plugins (because the solution was to just put together a load order that sometimes resulted in catastrophic results). With this new system, Paper refuses to complete startup with these loops present.
Thankfully, there's a fairly simple workaround to go back to the legacy plugin loading system: the -Dpaper.useLegacyPluginLoading flag! By setting its value to true, Paper will fall back to the old plugin loading system that we've been using for over 10 years.
For Minecraft servers running in our shared hosting plans, you can enable this setting by following these steps:
Keep in mind this workaround may not work indefinitely, and you should always make sure you aren't using plugins with dependency loops in them.
Navigate to your server's Startup tab in the panel.
Scroll down to find the option titled "**Paper legacy plugin loading**", and enable it.
Now restart your server to apply the changes.
Your server should now use the legacy plugin loading system.
The only real solution, though, would be for plugin developers to make sure their software doesn't have dependency loops. You can try reaching out to the authors of any plugins listed in your particular error message and see if they'd be willing to push out an update to address the problem. Most maintainers of popular plugins may already be aware though, so give them a few days to release an update.
Make sure your plugins don't depend on each other! If you have a "core" plugin providing libraries that are used by one or more of your plugins, this core plugin should never depend on your other plugins. Of course, those can still depend on the core via the plugin.yml file, but making a plugin depend on another one that also depends on the first will cause problems, as the plugin.yml file is what dictates what plugins will be started first. Unfortunately, this is outside the scope of this article and not something we can help you with. If you require further assistance with this, head over to the PaperMC forums or Discord server.
If you require any further assistance, please create a ticket here.
Created By: Raúl M.
Circular dependencies detected!
You have a plugin that is depending on a plugin which refers back to that plugin. Your server will shut down until these are resolved, or the strategy is changed.
Circular dependencies:
GriefPrevention depends on TheUnderground depends on GriefPrevention...
ShopGUIPlus depends on WildStacker depends on ShopGUIPlus...
ExecutableItems depends on SCore depends on ExecutableItems...
SCore depends on CustomPiglinsTrades depends on SCore...
SCore depends on ExecutableBlocks depends on SCore...
SCore depends on ExecutableEvents depends on SCore...
SCore depends on SParkour depends on SCore...
If you would like to still load these plugins, acknowledging that there may be unexpected plugin loading issues, run the server with -Dpaper.useLegacyPluginLoading=trueBut what does this really mean?
What are circular dependencies and why does this happen?
As the error may suggest, a circular dependency happens whenever a plugin depends on another, that also depends on the first plugin. I know this may sound confusing, so here's a better example:
| Plugin | Depends on |
|---|---|
| CoolLobbyPlugin | CoolCore |
| CoolCore | CoolLobbyPlugin |
We have two plugins in our server, CoolLobbyPlugin and CoolCore. CoolLobbyPlugin depends on CoolCore, this is entirely normal and is supported by Paper's new plugin loading system. However, CoolCore also depends on CoolLobbyPlugin, creating a circular dependency, which is unsupported.
Plugin dependency loops like this have been a problem causer for over a decade, regularly breaking plugins (because the solution was to just put together a load order that sometimes resulted in catastrophic results). With this new system, Paper refuses to complete startup with these loops present.
As a server owner, what can I do?
Thankfully, there's a fairly simple workaround to go back to the legacy plugin loading system: the -Dpaper.useLegacyPluginLoading flag! By setting its value to true, Paper will fall back to the old plugin loading system that we've been using for over 10 years.
For Minecraft servers running in our shared hosting plans, you can enable this setting by following these steps:
Keep in mind this workaround may not work indefinitely, and you should always make sure you aren't using plugins with dependency loops in them.
Navigate to your server's Startup tab in the panel.
Scroll down to find the option titled "**Paper legacy plugin loading**", and enable it.
Now restart your server to apply the changes.
Your server should now use the legacy plugin loading system.
The only real solution, though, would be for plugin developers to make sure their software doesn't have dependency loops. You can try reaching out to the authors of any plugins listed in your particular error message and see if they'd be willing to push out an update to address the problem. Most maintainers of popular plugins may already be aware though, so give them a few days to release an update.
I am the developer of one or more plugins listed in the error. What should I do?
Make sure your plugins don't depend on each other! If you have a "core" plugin providing libraries that are used by one or more of your plugins, this core plugin should never depend on your other plugins. Of course, those can still depend on the core via the plugin.yml file, but making a plugin depend on another one that also depends on the first will cause problems, as the plugin.yml file is what dictates what plugins will be started first. Unfortunately, this is outside the scope of this article and not something we can help you with. If you require further assistance with this, head over to the PaperMC forums or Discord server.
If you require any further assistance, please create a ticket here.
Created By: Raúl M.
Updated on: 20/02/2023
Thank you!