Skip to main content

Fix “Ambiguous plugin name” without losing plugin data

Applies to: Paper plugin loading where multiple active JARs declare the same internal name; choose builds for the installed server and Java releases.
Documentation checked .

Ambiguous plugin name means the loader found conflicting plugin identities. A common cause is leaving an old JAR in the active directory when uploading an update. Different filenames do not guarantee different plugin identities: two releases can declare the same internal name. Resolve that identity conflict without deleting the plugin's settings or saved data.

Record both candidates

Copy the ambiguity message and the two reported paths from the startup log. Note the server build and the time of the most recent upload. Open the file manager on the affected service and compare those paths carefully, including capitalization. Do not assume the JAR with the shorter or newer-looking filename is the correct one.

Read the release information for both files from their official sources. Establish whether they are two versions of one project, a renamed fork claiming the original identity, or separate components that should not be installed together. Companion plugins normally have their own documented identities; do not remove one solely because its project name looks similar.

Preserve the intended recovery point

Save a backup and download the relevant JARs and plugin configuration privately. If an update may already have migrated a database or data files, check the author's rollback notes. Keeping an older binary does not guarantee that it can safely read data written by a newer version.

Decide which release is supported by your exact Minecraft/Paper and Java versions. Historical versions in a documentation example are examples of duplicate identity, not recommended downloads. A current 26.x server and an older 1.21.11 deployment can require different plugin builds.

Remove the conflict from the active load path

Stop the server cleanly. Move the unwanted JAR outside the active plugins directory, retaining it as private recovery material. Do not move or erase the project's data folder. Avoid using a nested plugins subdirectory as an unexplained long-term archive; keep rollback files clearly separate from the deployment.

Check the supported update workflow as well. A pending replacement in Paper's update directory or an automated deployment can bring the duplicate back at the next restart. Coordinate with anyone uploading files so two staff members do not each restore a different release. Record the single intended version in your change note.

Renaming the duplicate JAR while leaving it active is not a reliable fix because the internal plugin name remains unchanged. Do not patch a JAR's metadata to pretend it is a second independent plugin; both copies may still target the same commands, files and database tables.

Verify one identity and the right data

Start once and inspect the startup log for the ambiguity message and any new loading error. Confirm the selected plugin version using its documented version command or startup output. Test a normal feature and check that the expected settings and saved records are still present.

If the wrong release loaded, stop and correct the active JAR set before continuing play. If a compatible rollback is necessary, restore the matched configuration and data through the author's procedure. Keep the failed attempt's logs. No world reset, broad plugin-folder deletion or server reinstall is needed to resolve duplicate plugin identity.

Official references

Paper ambiguous plugin-name error. Paper update workflow. Plugin internal name metadata.

No comments to display