How to Fix “Invalid plugin.yml” on a Minecraft Server

Direct answer

Invalid plugin.yml usually means the JAR is not a valid Bukkit/Paper plugin package. Paper specifically lists two common causes: you downloaded a mod or wrong artifact instead of a plugin, or the file was incomplete/corrupted during download or transfer.

Diagnosis to use: An invalid plugin.yml is plugin metadata inside the JAR, not the server owner’s ordinary config.yml.

Confirm you downloaded the server plugin artifact

Some projects distribute multiple files for Bukkit/Paper, Velocity, Fabric, Forge, NeoForge, BungeeCord, or APIs. Use the artifact named for your server platform; a Forge/Fabric mod cannot be made into a Paper plugin by renaming the file.

What to collect: Note the full error, especially “does not contain plugin.yml”, a missing main class, or an invalid API version. Check whether this JAR is actually a Bukkit/Paper plugin, a Velocity plugin or a Fabric/Forge mod.

Redownload from a trusted source

Download again from the project’s official Hangar, Modrinth, GitHub release, or documented site. If a command-line download saved an HTML error page with a .jar filename, the file will not contain valid plugin metadata.

Keep the JAR in the plugins root

Paper expects plugin JARs directly inside plugins/, not nested inside a ZIP or a subdirectory. Restart and check latest.log again after replacing the file.

Targeted repair: Install the official artifact for your exact server platform. If the developer shipped a broken JAR, report the error and use a known working release; avoid editing packed metadata on a live server.

Verify after the change: After restarting, confirm plugin startup logs contain no metadata exception, and test its actual functionality.

If you are the plugin developer

Validate the YAML syntax and required metadata in plugin.yml or the Paper plugin descriptor. Server owners should generally not modify third-party plugin metadata inside the release JAR.

Official references

These references were checked while preparing this fix. Version-specific behavior can change, so use the project documentation for your exact release when a detail differs.

Was this article helpful?

Help us improve this article

Tell us what is missing, unclear, outdated, or incorrect. You can also suggest something we should add.