If a Paper or Bukkit server stops with “Circular dependencies detected!”, inspect the cycle printed in the startup log, then update, remove, or reconfigure one of the named plugins so the dependency graph has a single direction. The error is a plugin load-order problem, not a damaged world. Only use -Dpaper.useLegacyPluginLoading=true as a temporary fallback while the plugins are repaired.
Godlike.Host offers modded Minecraft server hosting with one-click modpacks, a built-in mod installer and up to three free backups a day.
What the circular-dependencies error means
Paper loads plugins in an order that honors the relationships declared in each plugin’s metadata. A circular dependency exists when those relationships form a loop: Plugin A must load before Plugin B, B must load before C, and C must load before A. No first plugin can satisfy all three conditions, so Paper refuses to guess.
As an Amazon Associate I earn from qualifying purchases.
Paper’s plugin reference states: “If Paper detects a loop, your server will be shut down with an error.” The shutdown is deliberate. Starting in an arbitrary order could leave one plugin partly initialized, with failures that appear later as missing commands, broken events, data corruption, or inconsistent behavior. See the Paper plugins reference for the loader’s documented behavior.
The loop may contain two plugins or a longer chain. A typical diagnostic line looks like Plugin1 -> Plugin2 -> Plugin3 -> Plugin4 -> Plugin1. The names in your own message are authoritative; examples from another server are not a universal culprit list.
#1 Best Overall
Find the exact loop before changing anything
Stop restart attempts
Stop the server and prevent an automatic restart while you investigate. Repeated launches only reproduce the same failure and can make a managed panel’s console harder to read. Do not delete worlds, regenerate configuration, or replace Java before checking the plugin cycle.
Read the startup console and latest log
Copy the first circular-dependency message from the console, including every plugin name and the arrows showing the order. Then open logs/latest.log in the server directory. Paper’s basic troubleshooting guide uses the startup output to identify the loop, and its adding-plugins guide directs administrators to the latest log when diagnosing load failures.
Use the first complete loop you see, not a later stack trace. A later exception may be a consequence of the loader stopping and may point at a plugin that is merely downstream of the real ordering conflict.
Record versions and recent changes
- Write down the exact JAR filename and version for every plugin named in the loop.
- Note which plugin was installed, updated, downgraded, or removed immediately before the failure.
- Check whether
plugin.ymlorpaper-plugin.ymlwas edited, regenerated, or replaced. - Keep a backup of the server and a copy of the current plugin directory before testing.
How plugin metadata creates a loop
Paper reads ordering declarations from plugin metadata. The three relationships most relevant to this error are:
| Declaration | Meaning | How it can contribute to a cycle |
|---|---|---|
depend |
The named plugin is required and must be loaded first. | If two plugins each declare the other as a required dependency, each waits for the other. |
softdepend |
The named plugin is optional, but Paper attempts to load it first when it is present. | Two optional integrations can still request opposite ordering, even though neither is strictly required. |
loadbefore |
The plugin requests that another plugin load after it. | A loadbefore request can conflict with a dependency or ordering request that points the other way. |
These definitions are documented in Paper’s plugin.yml and paper-plugin.yml reference. A cycle can be introduced by a release that changed metadata even when the plugin’s visible features did not change.
Step-by-step repair workflow
1. Map the cycle
- Copy the complete arrow chain from the error.
- Draw each arrow as “must load before.” For example,
A -> Bmeans A is required or requested before B in the reported chain. - Mark the arrow that closes the loop. That edge is often the declaration added or changed by the newest plugin release.
Do not infer a cause from the alphabetical order of files in the plugins folder. Paper uses metadata, not filename order, to resolve dependencies.
Free tools Windows power users keep installed
One-click scans. No signup required.
2. Check the named plugins’ metadata and release notes
Inspect the JARs or the project’s documented configuration for depend, softdepend, and loadbefore entries. Compare the current release with the last version that started successfully. If a plugin’s documentation identifies a required companion, make sure that companion is the supported version rather than a similarly named fork or outdated build.
When a plugin bundles or shades another library, do not treat that library as a separate server plugin unless its documentation says to install it separately. Installing duplicate or incompatible copies can create additional loading conflicts, although the circular message itself is still caused by ordering declarations.
3. Reproduce with one controlled change
- Make a full backup of the world, configuration, and plugin directory.
- Move one suspect JAR out of
pluginsinto a temporary holding folder; do not delete it. - Start the server once and record whether the cycle disappears or changes.
- Stop the server before making the next change.
Change only one plugin per attempt. If several JARs are removed together, you may get a successful boot but lose the information needed to identify the incompatible relationship.
4. Choose the permanent fix
Use the result of the controlled test to select one of these repairs:
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Rank #3
- The classic UNO card game builds fun on game night with a Minecraft theme.
- UNO Minecraft features a deck and storage tin decorated with graphics from the popular video game.
- Players match colors and numbers to the card on top of the discard pile as in the classic game.
- The Creeper card unique to this deck forces other players to draw 3 cards.
- Makes a great gift for kid, teen, adult and family game nights with 2 to 10 players ages 7 years and older, especially Minecraft and video game fans.
- Update: install a release whose metadata no longer requests the reciprocal ordering, after confirming it supports your Paper build and Minecraft version.
- Roll back: restore the last known-good plugin version if the loop began immediately after an update. Keep the newer JAR outside the server so it is not loaded accidentally.
- Remove: leave the plugin disabled if it is optional or has no compatible release. Removing one edge from the graph is safer than forcing an arbitrary order.
- Reconfigure integration: if a plugin offers an option to disable an optional hook or bridge, use that setting so only the necessary plugin remains in the ordering relationship.
- Contact the maintainer: send the complete cycle, Paper version, Minecraft version, plugin versions, and the relevant log excerpt. Paper’s troubleshooting guidance says there is often a problematic plugin and recommends reporting the issue to its authors; see the troubleshooting page.
5. Verify a clean startup
After the server starts, review the entire boot log rather than stopping at the first “Done” line. Confirm that every plugin in the former cycle reports a normal enable message, that required commands register, and that no new dependency or class-loading errors appear. Join with a test account and exercise the features that use the affected plugins before returning the server to players.
What a healthy dependency design looks like
The stable pattern is a one-way graph. A shared core or API plugin loads first, and feature plugins depend on that core without depending on one another. For example:
SharedCore
├── EconomyFeature
└── ClaimsFeatureAn unstable pattern is two feature plugins that each declare the other as a required or preferred predecessor. If both integrations are optional, the maintainer should normally choose one direction or remove the ordering request and discover the other plugin at runtime. The exact change belongs in the plugin’s metadata and source; server administrators should not edit a signed or packaged JAR unless the maintainer explicitly provides that procedure.
Temporary workaround: enable legacy plugin loading
Paper provides a compatibility switch that permits cyclic loading:
-Dpaper.useLegacyPluginLoading=trueThe documented default is false. Paper’s system-properties reference describes the property, while the plugin reference warns that the legacy path may not be supported indefinitely. Paper’s troubleshooting guidance treats it as a last resort because it can produce hard-to-debug plugin behavior.
Rank #4
- Now Minecraft lovers can play a special version of UNO!
- Same as Basic UNO but features Minecraft characters and includes special Creeper rule card. Draw this card and the other players have to draw three more cards from the pile!
- The goal is to get rid of all the cards in your hand.
- First player or team to 500 wins.
- When you're down to one card, don't forget to yell "UNO"!
Linux, macOS, or a shell startup script
Put the property on the Java command before -jar. For example:
java -Dpaper.useLegacyPluginLoading=true -Xms2G -Xmx4G -jar paper.jar noguiKeep the existing memory settings, Paper JAR name, and other JVM flags from your script. The important placement rule is that the -D option belongs to Java’s options, before -jar; placing it after paper.jar passes it to Paper as an application argument instead of setting the JVM property.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Windows batch file
Edit the existing line that starts the server and insert -Dpaper.useLegacyPluginLoading=true alongside the other Java options, before -jar. Save a backup of the batch file so you can remove the switch after the plugin repair.
Managed hosting panel
Some panels expose the property as a startup variable, checkbox, or advanced Java option. Add the exact property value to the panel’s Java command, save it, and restart once. One documented example is a panel setting labeled “Paper legacy plugin loading”; its instructions are at
