How to Fix permissions.yml Errors
A broken permissions.yml doesn't stop the server, but none of its permissions load. How to read the warning, fix tabs and structure, and what the file can do.
Quick Fix
Replace tabs with spaces at the line and column the warning names, check the default, children and description keys, and restart the server.
Error Message
Server permissions file permissions.yml is not valid YAML: while scanning for the next tokenHow to Fix
Replace every tab with spaces. The warning ends with the line and column where reading stopped.
Give each node only the keys Bukkit reads: description, default and children.
Set default to true, false, op or notop.
Write children as a list, where every node listed is granted, or as a map of nodes to true or false.
Leave the file empty if you don't use it. An empty permissions.yml is skipped with a line saying it is empty, ignoring it, and a missing file is skipped without a message.
Check permissions-file under settings in bukkit.yml. It decides which file is read and is permissions.yml by default.
On Paper, load-permissions-yml-before-plugins under misc in config/paper-global.yml is true by default, so plugins can already see these permissions when they enable.
Common Causes
- Tabs used for indentation. YAML doesn't allow them, and the warning says found character '\t(TAB)' that cannot start any token.
- Another YAML syntax error, such as a missing colon or uneven indentation. Bukkit then skips the whole file, so none of the permissions in it exist.
- A default value Bukkit doesn't know. The log says 'default' key contained unknown value, and that node isn't loaded.
- A children entry of the wrong type. children has to be a list of nodes or a map of nodes to true, false or a nested node, otherwise the log shows 'children' key is of wrong type or Child 'name' contains invalid value.
- The same node is defined twice, for example as a full entry under two parents. The log says Permission in permissions.yml was already defined.
Diagnostic Steps
- Back up permissions.yml.
- Find the line and column from the warning in latest.log.
- Replace tabs and fix the keys and values.
- Restart the server and check the log for permission warnings.
FAQ
Should I use permissions.yml or a plugin?
permissions.yml only defines permission nodes with a default and children. It can't give permissions to a single player or a group, so for that you need a permissions plugin such as LuckPerms.
Does a broken permissions.yml stop the server?
No. Bukkit logs a warning and skips the file, so the server starts without the permissions defined in it.
Which values does default accept?
true, false, op and notop. Bukkit also accepts isop, operator, admin, !op, notoperator and notadmin, and it ignores case.
