Paper and Spigot plugin.yml errors, explained

Each message below was printed by a real Paper 26.3 server while loading a test plugin with one mistake in its plugin.yml. Find the line from your log, see what causes it and how to fix it.

• "Cannot add self-loop edge on node" crashes the server at startup

  The plugin lists its own name in depend, softdepend or loadbefore. We reproduced the crash with each of the three keys.

• StackOverflowError in PermissibleBase.calculateChildPermissions

  A loop in children under permissions: two or more permissions that include each other. It crashes at startup when any permission in the loop is given to operators by default (default: op, default: true, or no default at all, which means op), because the console is an operator. With default: false the server starts, and the same code runs later when a player is given one of them.

• "Restricted name, cannot use 0x20 (space character) in a plugin name"

  The name in plugin.yml contains a space.

• "Restricted name, cannot use ... as a plugin name"

  The plugin is named bukkit, minecraft, mojang, spigot or paper. Upper or lower case does not matter.

• "name ... contains invalid characters"

  The name in plugin.yml has a character outside that set.

• "main may not be within the org.bukkit namespace"

  The main value starts with org.bukkit., usually because the class was created inside the wrong package.

• "version is not defined" (also "name is not defined", "main is not defined")

  plugin.yml has no version (or name, or main). It also happens when the key is there but misspelled or indented under another key.

• "depend is of wrong type" (also softdepend, loadbefore, authors)

  The value is written as plain text instead of a list.

• "commands are of wrong type"

  Usually a command written on one line, like commands: home, or a command whose description is put right after its name.

• "load is not a valid choice"

  load is set to something other than STARTUP or POSTWORLD.

• "Unsupported API version"

  The plugin was built for a newer Minecraft version than the server runs, or api-version has a typo such as 26.10 instead of 26.1.

• "Legacy plugin ... does not specify an api-version"

  plugin.yml has no api-version, or it is lower than 1.13.

• "'default' key contained unknown value"

  The default of a permission is not one of the allowed values: true, false, op, not op (also written notop, !op, admin, isop and a few other spellings).

• "Child '...' contains invalid value"

  Usually true written in quotes, which makes it text instead of a yes/no value.

• "Could not load command ... Illegal Characters"

  The command or alias name contains :. The colon is reserved for the plugin:command form that the server creates on its own.

• "Bad artifact coordinates ..., expected format is <groupId>:<artifactId>:<version>"

  An entry in libraries is missing the group, artifact or version part.

• "found character '\t(TAB)' that cannot start any token"

  A line is indented with a Tab. The line number is in the message.

• "Unknown/missing dependency plugins"

  The required plugin is missing, or the name in depend does not match the other plugin's name exactly (case matters).

• paper-plugin.yml: "[api-version] ... A value is required for this field"

  paper-plugin.yml has no api-version.

• ClassNotFoundException for the plugin main class

  A typo in main, a package that was renamed without updating plugin.yml, or a jar built without the compiled classes.