Server doesn't seem to gracefully shut down

[FractalRose]

Hey all, I'm sure this is user error but I've been trying for ages and I can't seem to get this to work nicely.
I'm using this docker on Unraid, but for some reason the docker doesn't seem to be gracefully shutting down.

When I run the /stop command from within the game as a client (ie op user), the server gracefully shuts down, and the logs show all the lines about saving and shutting down.

But when I run the docker stop command (or stop the docker through the Unraid UI), the logs just don't show anything at all (no save or shut down lines in the log), and the docker seems to shut down suspiciously fast.

Am I missing something, or is this normal?

Thanks in advance!

[itzg]

That is not normal. Normally a container stop will send a "TERM" signal which will then be handled by issuing a "/stop" command.

Please re-test with a completely vanilla server where only the env variable EULA is set to true. Provide the logs if the server is still not stopping as it should be.

This is more likely an issue that needs to be discussed with Unraid since they maintain the app wrapper of my image.

[FractalRose]

Just tried, logs don't show anything new when docker stop is run unfortunately.

[itzg]

Thanks for checking. That might mean then that they're sending the wrong signal on container-stop.

[FractalRose]

Thanks for confirming - should I be telling the Unraid team that the docker is expecting a "TERM" signal on container stop and it's potentially not happening?

[itzg]

Yeah that's probably a good place to start. Shouldn't be surprising to them though since that's the default behavior

https://docs.docker.com/reference/cli/docker/container/stop/

[FractalRose]

So while I'm waiting for a response, I've tried to set the --stop-signal flag to various things (like 15, TERM and SIGTERM) and none of them work either, though I'm not 100% sure I'm setting it up correctly.
Also, when I stop the docker, the status says "Exited (143)", which is signal 15 (TERM). This kind of suggests it's actually getting the right signal, it's just not doing the right thing with it (I believe documentation says "Exited (0)" is a graceful shut down after a TERM signal). Just to confirm, is the latest/correct repository itzg/minecraft-server?

[itzg]

Continuing from the example above with a container named "mc", get a process listing inside the container:

docker exec mc ps -ef

and processes should include at least these two:

UID        PID  PPID  C STIME TTY          TIME CMD
minecra+     1     0  0 02:53 pts/0    00:00:00 mc-server-runner --stop-duration 60s java -Xmx1G -Xms1G -jar minecraft_server.1.21.9.jar
minecra+   433     1 99 02:53 pts/0    00:00:28 java -Xmx1G -Xms1G -jar minecraft_server.1.21.9.jar

Then send the same TERM signal to PID 1 as what a docker stop does:

docker exec mc kill -TERM 1

And again the container output should be

2025-10-01T02:55:16.336Z	INFO	mc-server-runner	gracefully stopping server...
2025/10/01 02:55:16 Stopping with rcon-cli
[02:55:16] [RCON Listener #1/INFO]: Thread RCON Client /0:0:0:0:0:0:0:1 started
[02:55:16] [Server thread/INFO]: [Rcon: Stopping the server]
2025-10-01T02:55:16.346Z	INFO	mc-server-runner	Waiting for completion...
[02:55:16] [RCON Client /0:0:0:0:0:0:0:1 #2/INFO]: Thread RCON Client /0:0:0:0:0:0:0:1 shutting down
[02:55:16] [Server thread/INFO]: Stopping server
[02:55:16] [Server thread/INFO]: Saving players
[02:55:16] [Server thread/INFO]: Saving worlds
[02:55:16] [Server thread/INFO]: Saving chunks for level 'ServerLevel[world]'/minecraft:overworld
[02:55:16] [Server thread/INFO]: Saving chunks for level 'ServerLevel[world]'/minecraft:the_nether
[02:55:16] [Server thread/INFO]: Saving chunks for level 'ServerLevel[world]'/minecraft:the_end
[02:55:16] [Server thread/INFO]: ThreadedAnvilChunkStorage (world): All chunks are saved
[02:55:16] [Server thread/INFO]: ThreadedAnvilChunkStorage (DIM-1): All chunks are saved
[02:55:16] [Server thread/INFO]: ThreadedAnvilChunkStorage (DIM1): All chunks are saved
[02:55:16] [Server thread/INFO]: ThreadedAnvilChunkStorage: All dimensions are saved
[02:55:16] [Server thread/INFO]: Thread RCON Listener stopped
2025-10-01T02:55:16.808Z	INFO	mc-server-runner	Done

[FractalRose]

I spun up a completely new vanilla one just to test it. Here are the first few lines the log spits out:

[init] Changing ownership of /data to 1000 ...
[init] Running as uid=1000 gid=1000 with /data as 'drwxr-xr-x 1 1000 1000 18 Oct  2 07:23 /data'
[init] Image info: buildtime=2025-10-01T12:30:46.599Z,version=java21,revision=b7859d7496b66a2064c4fb75c08604a735fafab6
[init] Resolving type given VANILLA
[init] Resolved version given LATEST into 1.21.9
[init] Downloading 1.21.9 server...
[init] Copying any configs from /config to /data/config
[init] Creating server properties in /data/server.properties
[init] Disabling whitelist functionality
[init] Setting mode
[mc-image-helper] 07:23:16.876 INFO  : Created/updated 17 properties in /data/server.properties
[init] Setting initial memory to 1G and max to 1G
[init] Starting the Minecraft server...
[mc-image-helper] 07:23:16.876 INFO  : Created/updated 17 properties in /data/server.properties
[init] Setting initial memory to 1G and max to 1G
[init] Starting the Minecraft server...

Then it goes on to do the normal running of the server.

Running docker exec mc ps -ef gives the following:

UID        PID  PPID  C STIME TTY          TIME CMD
minecra+     1     0 99 07:27 ?        00:00:40 java -Xmx1G -Xms1G -jar minecraft_server.1.21.9.jar
root       489     0 14 07:27 ?        00:00:00 ps -ef

Running docker exec mc kill -TERM 1 still closes it immediately, no graceful shutdown, and docker status after shut down is Exited (143).

Would you like me to send the entire log as a txt file?

[itzg]

Interesting, some of that is still unexpected.

Can you now set the env var DEBUG to "true" and provide those startup logs? It'll be a lot of output, so like you offered, you'll probably need to drag and drop the text file into the response.

[FractalRose]

I just ran the same new docker, but with debug on. Interestingly, a lot of the [init] lines are missing now.

Here's the whole extract:

+ shopt -u -o xtrace
+ compare_version 1.21.9 lt 1.7
+ local left_version=1.21.9
+ local comparison=lt
+ local right_version=1.7
+ [[ -z 1.21.9 ]]
+ [[ -z 1.7 ]]
+ [[ 1.21.9 == a* ]]
+ [[ 1.21.9 == b* ]]
+ [[ 1.7 == a* ]]
+ [[ 1.7 == b* ]]
+ local left_version_channel=1
+ [[ 1 =~ [0-9] ]]
+ left_version_channel=r
+ local right_version_channel=1
+ [[ 1 =~ [0-9] ]]
+ right_version_channel=r
+ [[ lt == \l\t ]]
+ [[ r < r ]]
+ [[ lt == \l\t ]]
+ [[ r > r ]]
+ [[ lt == \g\t ]]
+ [[ lt == \g\t ]]
+ [[ lt == \l\e ]]
+ [[ lt == \l\e ]]
+ [[ lt == \g\e ]]
+ [[ lt == \g\e ]]
+ [[ lt == \e\q ]]
+ local result=1
+ case $comparison in
++ echo -e '1.21.9\n1.7'
++ sort -V
++ head -n1
+ [[ 1.7 == \1\.\2\1\.\9 ]]
+ return 1
+ isTrue ''
+ case "${1,,}" in
+ return 1
+ rm -f /data/.mc-health.env
+ mcServerRunnerArgs=(--stop-duration "${STOP_DURATION:-60}s")
+ isTrue false
+ case "${1,,}" in
+ return 1
+ [[ -n 30 ]]
+ mcServerRunnerArgs+=(--stop-server-announce-delay "${STOP_SERVER_ANNOUNCE_DELAY}s")
+ isTrue ''
+ case "${1,,}" in
+ return 1
+ [[ VANILLA == \C\U\R\S\E\F\O\R\G\E ]]
+ [[ VANILLA == \C\U\R\S\E\F\O\R\G\E ]]
+ [[ minecraft_server.1.21.9.jar =~ run.sh ]]
+ '[' -f /data/bootstrap.txt ']'
+ log 'Starting the Minecraft server...'
+ local oldState
++ shopt -po xtrace
+ oldState='set -o xtrace'
+ shopt -u -o xtrace
+ finalArgs=($JVM_XX_OPTS $JVM_OPTS $expandedDOpts)
+ [[ -n '' ]]
+ finalArgs+=(-jar "$SERVER")
+ finalArgs+=("$@" $EXTRA_ARGS)
+ isTrue false
+ case "${1,,}" in
+ return 1
+ isTrue false
+ case "${1,,}" in
+ return 1
+ isTrue true
+ case "${1,,}" in
+ return 0
+ exec java -Xmx1G -Xms1G -jar minecraft_server.1.21.9.jar
[init] 2025-10-02 07:49:59+10:00 Starting the Minecraft server...
Starting net.minecraft.server.Main
[07:50:05] [ServerMain/INFO]: Environment: Environment[sessionHost=https://sessionserver.mojang.com, servicesHost=https://api.minecraftservices.com, profilesHost=https://api.mojang.com, name=PROD]
[07:50:07] [ServerMain/INFO]: Loaded 1461 recipes
[07:50:07] [ServerMain/INFO]: Loaded 1574 advancements
[07:50:07] [Server thread/INFO]: Starting minecraft server version 1.21.9
[07:50:07] [Server thread/INFO]: Loading properties
[07:50:07] [Server thread/INFO]: Default game type: SURVIVAL
[07:50:07] [Server thread/INFO]: Generating keypair
[07:50:07] [Server thread/INFO]: Starting Minecraft server on *:25565
[07:50:07] [Server thread/INFO]: Using epoll channel type
[07:50:07] [Server thread/INFO]: Preparing level "world"
[07:50:07] [Server thread/INFO]: Loading 0 persistent chunks...
[07:50:07] [Server thread/INFO]: Preparing spawn area: 100%
[07:50:08] [Server thread/INFO]: Time elapsed: 14 ms
[07:50:08] [Server thread/INFO]: Done (0.324s)! For help, type "help"
[07:50:08] [Server thread/INFO]: Starting remote control listener
[07:50:08] [Server thread/INFO]: Thread RCON Listener started
[07:50:08] [Server thread/INFO]: RCON running on 0.0.0.0:25575

[itzg]

Thanks. It's acting like the env var EXEC_DIRECTLY is set to "true". It really should be left at the default of "false" or else you lose features like graceful signal handling.

[FractalRose]

Oh my god that's all it was. For those who use Unraid, the template available has EXEC_DIRECTLY set to true as default out of the box - just delete or change it to false. I just never questioned it because the documentation doesn't directly say it stops the automated control.

Thanks so much for the help!

[itzg]

A long journey for an easy fix 😀

I might actually remove that variable's handling since it was originally there for Forge colorized logs. That's now supported regardless.

[FractalRose]

Very long journey for what is, as I said at the start, user error!
Thanks for your patience and help, can't wait to move my server over to this docker so that my players can stop asking me to update the server 😂