Minecraft server properties live in server.properties, a plain-text file in the server’s main folder that the server creates on its first start. Each line is one setting written as key=value, such as max-players=20 or difficulty=easy. Stop the server, change the value in a text editor, and start it again: the server only reads the file at startup. Below are the settings that matter in Minecraft 26.3, what each value means, and the fixes for the whitelist, difficulty and MOTD problems people hit most.
Where is server.properties?
It sits in the server’s working directory, usually the same folder as server.jar, next to eula.txt, ops.json and the world folder. If it isn’t there, the server hasn’t been started yet. On a hosting panel, look in the root of the file manager.
Three things to know before you edit the configuration:
- Use a plain-text editor (Notepad, nano, VS Code), never Word. The file is UTF-8.
- The server rewrites the file on every start. Missing keys are added, invalid values are reset to the defaults, and any comments you wrote are removed.
- Changes need a restart. Editing the file while the server runs does nothing until the next start. Stop first, then edit.
Minecraft server properties explained: the settings that matter
A 26.3 server generates around 70 keys, but most groups only ever change a dozen. These are those MC server settings, their defaults and what to set them to. Everything else (resource packs, management protocol, query, text filtering) can stay at default for a normal survival or creative server.
| Key | Default | What it does |
|---|---|---|
motd |
A Minecraft Server | The message under your server’s name in the server list |
max-players |
20 | Players allowed online at once |
difficulty |
easy | peaceful, easy, normal or hard |
gamemode |
survival | Default mode: survival, creative, adventure, spectator |
force-gamemode |
false | true puts players back in the default mode every time they join |
hardcore |
false | Creates the world in hardcore mode: difficulty locked to hard, dead players can only spectate. Set it before the world is generated |
white-list |
true | Only players on the whitelist can join (default changed to true in 26.3) |
enforce-whitelist |
false | Kicks online players who aren’t listed when the whitelist is reloaded |
online-mode |
true | Checks every player against Minecraft’s account servers |
level-name |
world | The world folder to load or create |
level-seed |
blank | World seed; blank means random |
level-type |
minecraft:normal | minecraft:flat, minecraft:large_biomes, minecraft:amplified, minecraft:single_biome_surface |
generator-settings |
{} | Customises flat and single-biome worlds |
view-distance |
10 | How many chunks the server sends each player (3-32) |
simulation-distance |
10 | How far from players mobs and crops are updated (3-32) |
spawn-protection |
16 | Area around spawn only ops can build in; 0 turns it off |
allow-flight |
false | Stops the server kicking Survival players who fly with mods |
pause-when-empty-seconds |
60 | Pauses the server after this long with nobody online |
server-port |
25565 | The TCP port players connect to |
server-ip |
blank | Leave blank so the server listens on every address |
op-permission-level |
4 | The level new ops get |
Settings that moved. Since 1.21.9, pvp, enable-command-block, allow-nether and spawn-monsters are no longer in server.properties; they’re game rules. On current versions, use /gamerule pvp false, /gamerule spawn_monsters false, /gamerule command_blocks_work true and /gamerule allow_entering_nether_using_portals false. On 1.21.8 and older, they’re still properties. The command side is in the Minecraft server commands guide.
How to whitelist a Minecraft server
A whitelist means only the players you list can join, which is the simplest way to keep a friends server private. Turn it on with white-list=true (already the default on 26.3), then add players from the console with whitelist add Name. They don’t need to be online. Operators can always join, whitelisted or not.
- Check
white-list=trueinserver.properties, or runwhitelist on. - Add each friend:
whitelist add Steve. Remove withwhitelist remove Steve. - Check the list with
whitelist list. - If you edit
whitelist.jsonby hand, runwhitelist reloadafterwards.
The file format, if you ever need it:
[
{ "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5", "name": "Notch" }
]
Want players who aren’t on the list kicked the moment you remove them? Set enforce-whitelist=true as well.
“You are not whitelisted on this server”: what it means
It means the server’s whitelist is on and your account isn’t on it. Being “not whitelisted” doesn’t mean you’re banned (that message is different): the owner just hasn’t added you yet. Ask them to run whitelist add YourName.
Why am I not whitelisted when I am?
Check these, in order:
- The name is spelled differently from your Minecraft username. Remove and re-add it.
whitelist.jsonwas edited but not reloaded. Runwhitelist reload.- The server runs with
online-mode=false. Offline servers use a different UUID for each name, so entries made with your real UUID don’t match. The Minecraft Wiki also notes a whitelist is ineffective in offline mode, since anyone can join under a listed name. Keeponline-mode=true. - You’re connecting to a different server than the one you whitelisted on, for example a second instance on another port.
Still stuck? There’s a longer checklist in the “you are not whitelisted” fix.
How to change Minecraft server difficulty
You can change server difficulty two ways. For a permanent change, stop the server, set difficulty=normal (or peaceful, easy, hard) in server.properties and start it. To change it right now, an op runs /difficulty hard, which applies immediately. To check the current difficulty, run /difficulty with no value, or look at the line in the file.
The legacy numbers still work too: 0 is peaceful, 1 easy, 2 normal, 3 hard. More detail in how to change server difficulty.
Minecraft server MOTD: colours and two lines
The motd property is the text players see under your server name. It supports Minecraft’s § formatting codes, and because the file is UTF-8 you can type the § directly (or write it as \u00A7). \n starts a second line.
motd=§aFriends SMP §7| §eSurvival 26.3\n§fWhitelist only, ask in Discord
Put the colour code before any bold or underline code, since a colour code resets formatting. Keep it short: the wiki warns a MOTD over 59 characters can make the server list report a communication error. Online MOTD generators just build this string for you; paste the result after motd=.
online-mode: what it does and why to leave it on
online-mode=true makes the server check every joining player against Minecraft’s account servers. Turning it off lets anyone join under any name, including an admin’s, and breaks the whitelist. On a normal friends or community server, leave it on.
World generator settings
level-type picks the world preset and generator-settings customises it. Both only affect a world when it’s first generated: changing them later does nothing to existing chunks. To try a new preset, stop the server, change level-name to a new folder name, set the type and start it. A flat world is level-type=minecraft:flat, and a hardcore world needs hardcore=true set before that first start.
Settings for performance
view-distance and simulation-distance drive most of the server’s work. Lowering simulation-distance to 6 or 8 cuts mob and redstone processing near players; lowering view-distance cuts what the server sends. The default of 10 is fine for a small group. When the server lags, these are the first two to change, and the lag fix guide covers what to try next.
Distant Horizons server settings
Distant Horizons is a level-of-detail mod for Fabric, Forge and NeoForge, not a server.properties setting, so you won’t find it in this file. It’s optional on the server: if both the server and the player have it, the server sends far-away terrain to players who have Distant Generation Enabled, and turning distant generation off on the server stops that. Its settings live in the mod’s own config file.
Common mistakes
| Symptom | Cause | Fix |
|---|---|---|
| Your change disappeared | Edited while running, or an invalid value was reset to default | Stop first, edit, start; check spelling of the value |
| Friends can’t join a new 26.3 server | Whitelist on by default | whitelist add Name, or white-list=false |
pvp=false does nothing |
PvP is a game rule since 1.21.9 | /gamerule pvp false |
| Players can’t connect after changing the port | Router and firewall still forward the old port | Update the forward; see port forwarding |
| New world settings ignored | level-name still points at the old world |
Use a new folder name |
| Spawn protection doesn’t apply | No ops on the server, which disables it | Op yourself |
FAQ
Can I change server properties while the server is running?
The file, no: the server reads it only at startup. Some things can be changed live with commands instead, like /difficulty, /whitelist on and game rules.
What happens if I delete server.properties?
The server creates a fresh one with default values on the next start. Your world is untouched, but every custom setting is gone, so keep a copy.
How do I check my Minecraft server settings?
Open server.properties, or run /difficulty and /gamerule <rule> in-game to read current values.
What is a whitelist in a Minecraft server?
The list of players allowed to join. With it on, everyone else is turned away with “You are not whitelisted on this server.”
How do you get whitelisted on a Minecraft server?
Ask the owner or an admin to add your exact username. There’s no way to add yourself without op or console access.
Skip the file editing
On GameTeam’s Minecraft server hosting you can edit server.properties in the panel’s file manager, or just describe the change. Type “Max-players 30, difficulty hard, MOTD: Welcome to the SMP, whitelist Steve and Alex” and the AI copilot reads the file, makes the edits, runs the whitelist commands, reads the values back so you can see what changed, and restarts the server. It knows which settings are game rules on your version, so “turn PvP off” lands in the right place. The copilot is included on every plan; you pay per GB of RAM from $0.49/GB a week, with unlimited slots. New to all this? Start with how to make a Minecraft server, or put the whole config on autopilot with Minecraft server hosting.
