Guide Stop losing plugin settings: edit YAML safely and test configuration persistence

[BlackSpigot Guides]

First distinguish a YAML syntax problem from a plugin saving the wrong values.

For server owners
Keep a copy of the working configuration. Follow that plugin's reload procedure, or stop it before editing if it writes its configuration during shutdown. Change one setting, preserve indentation and avoid duplicate keys. Read the plugin's startup messages after restarting. If a setting reverts, compare the file immediately after your edit, after startup and after clean shutdown; the first point where it changes is useful evidence.

For plugin authors
Ship sensible defaults in the JAR. JavaPlugin.saveDefaultConfig() creates the default file when it is missing; it is not a reason to overwrite a member's existing file on every start. Treat a configuration-version migration separately from a normal startup. Validate required values and ranges before enabling the feature that uses them. An absent value and a deliberately configured zero may mean different things.

A small persistence test

• Start with no configuration and verify defaults appear.
• Stop, set one valid non-default value and restart. Verify that value is used.
• Stop again and verify the value remains in the file.
• Try an invalid value on the test server. The log should explain the setting and expected type.
• Restore the valid file and confirm the feature recovers.

When reporting a bug, include the smallest relevant YAML section, the exact plugin build and which step changed the file. Remove tokens and database passwords before posting.

Configuration API reference