Symptoms: The server behaves unexpectedly, settings have no effect, config changes disappear, or some features never work at all. Most of these problems come from faulty configuration files (server.properties, spigot.yml, paper.yml, bukkit.yml).

Possible Causes

  • Meaningless values entered in server.properties (max-players=0, view-distance=32 and so on)
  • spigot.yml or paper.yml contains a YAML syntax error, so the server falls back to the defaults
  • The server was not fully restarted after the config was changed — /reload is not enough
  • The same setting is defined in more than one file and they conflict (e.g. view-distance in both server.properties and spigot.yml)
  • A tab character has been used in a YAML file — YAML only accepts spaces
  • Wrong file permissions mean the server cannot read or write the file

Step-by-Step Fix

Step 1

Take a backup, then quickly review the values inside server.properties. Most problems are hiding right there

bash
cp server.properties server.properties.bak
grep -E "max-players|view-distance|simulation-distance|online-mode|server-port|level-name" server.properties

Step 2

Validate every YAML file for syntax. One wrong space makes the server ignore that file entirely

bash
for f in *.yml plugins/*/config.yml; do python3 -c "import yaml,sys; yaml.safe_load(open(sys.argv[1]))" "$f" 2>&1 | head -3; done

Step 3

Whenever you change a config, restart the server COMPLETELY. The /reload command does not apply server.properties changes

bash
# to the screen session:
screen -S mc -X stuff "stop\n"
# with pm2:
pm2 restart minecraft

Step 4

Find the conflict: search for the same setting across every config file

bash
grep -rn "view-distance" server.properties *.yml plugins/*/config.yml 2>/dev/null

Step 5

Check whether your YAML files contain tabs

bash
grep -nP "\t" *.yml && echo "TAB found — convert to spaces" || echo "Clean"

Step 6

Give file ownership to the minecraft user. Files edited as root cause permission problems later on

bash
chown -R minecraft:minecraft /home/minecraft/server/
find . -name "*.yml" -o -name "*.properties" | xargs chmod 644

Step 7

If you use Paper, keep the config warnings on — it writes faulty settings into the log at startup

bash
# config/paper-global.yml
misc:
  print-config-warnings: true

Step 8

To verify plugin configs, watch the loaded log lines during startup

bash
tail -f logs/latest.log | grep -iE "config|loaded|properties"