Getting Started

A friend cannot connect to my server

Open the Dashboard and read the How players join card: it shows the address to type for each case - on this computer, on your home network (this computer's network address, not 127.0.0.1) and from the internet (the router steps; Look up my public address contacts api.ipify.org only when you press it) - and says when only this computer can connect and why. A container server created as "this computer only" can be opened to your network in Server Settings → Network and ports (the server has to be stopped; MineUI rebuilds the container around the same data volume, so the world, mods, settings and backups stay). MineUI does not configure routers or firewalls - the card names the steps for your system. With Podman on Windows the server runs inside WSL and other devices cannot reach it until Windows is set up (mirrored networking on Windows 11 22H2 or newer; on Windows 10, TCP-only port forwarding); UDP voice ports may not work there. A voice chat mod also needs its own port published (Extra ports for mods) and opened on the router and firewall; MineUI only publishes the port, it does not install or configure the mod.

The managed server won't start - EULA not accepted

Mojang requires accepting the EULA before a server will boot. The Create Server stepper has an explicit EULA step - go back through it, or set eula=true via the Config page, then start the server again.

No container runtime - neither Podman nor Docker is installed

Since MineUI 2.7.0 the app tells you what to do: wherever a container is needed and no runtime is found - the create-container flow, the dashboard of a container server, Server Settings - it shows the install steps for Linux, Windows, and macOS with copyable commands, opening on your OS, and a Check again button. The same steps are in Installing Podman or Docker above. Either runtime works; MineUI prefers Podman when both exist.

Windows + Podman: the container runs and the log says Done, but the dashboard stays Offline and RCON does not connect

Two causes, both on Podman's WSL provider. (1) A server made with MineUI 2.7.1 or earlier was published on 127.0.0.1 inside the Podman machine, which Windows cannot reach; 2.7.2 publishes the ports so they arrive on the Windows host's own 127.0.0.1 - update, delete the container (Server Settings → Danger zone → Delete container; the world can be kept) and create the server again. (2) The machine runs rootful (podman machine inspect --format {{.Rootful}} says true): a rootful machine publishes with NAT rules, not a listening socket, and WSL's localhost relay only mirrors listening sockets, so its ports never reach Windows. Switch it to rootless - podman machine stop; podman machine set --rootful=false; podman machine start - then create the server again (the two modes keep separate containers; copy the world out first with podman cp if it matters). MineUI 2.7.3 detects this and says so on the dashboard and the Status page, with the VM address the server answers at meanwhile.

Creating or starting a container fails with "crun: controller pids is not available under /sys/fs/cgroup/non-systemd/…"

Podman gives every container a default pids limit, and on some Podman machines (seen on WSL) the cgroup tree cannot take one. MineUI 2.7.1 handles it: when the runtime reports exactly this, the half-made container is removed and created once more with no pids limit, the way Docker runs containers. Update to 2.7.1 or newer and create the server again. On 2.7.0, remove the container with the runtime CLI (podman rm -f <name>) first. If the error appears when you press Start (a server whose ports were changed in 2.11.0 gets the limit back), update to 2.11.1: Start lifts the limit in place and tries again. On 2.11.0, run podman update --pids-limit=0 <name> once and start again. If it still fails (the lift is refused, or this computer gives containers no pids controller at all), 2.12.0 opens a dialog on Start with the command to lift the limit by hand and, on Linux, the systemd setting that gives your containers the controller, ready to copy.

MineUI says to install Podman or Docker, but one is installed

Three causes. (1) The runtime is installed but not running - Docker Desktop is closed, or the podman machine is stopped. Before 2.9.0 MineUI reported that as nothing installed; 2.9.0 says the runtime is installed but not responding and how to start it (open Docker Desktop, or podman machine start), then Check again. (2) The Linux AppImage on 2.8.0 or earlier: the AppImage pointed podman at its own bundled, older libseccomp, so every podman call failed (undefined symbol: seccomp_export_bpf_mem) and MineUI found no runtime on a machine that has Podman. 2.9.0 gives podman, docker and java a clean environment inside an AppImage - update; the .deb was never affected. (3) A short PATH: an app started from a launcher can have a shorter PATH than your terminal (common with Homebrew on macOS), and MineUI finds the runtime by running the podman or docker command. Put the full path to the binary in Server Settings → Advanced → Runtime binary override and press Check again - since 2.9.0 the override also works while the runtime setting is on Auto. If both runtimes are installed, MineUI prefers Podman; the Container runtime setting picks one explicitly.

Backups or mods look empty on a stopped container server

Fixed in 2.9.0. Before it, the backups and mods of a stopped container server were invisible: the page said "No backups yet" - although restoring requires the server to be stopped. Listing and deleting now work while the container is stopped, and a listing that fails is shown as an error, never as an empty list. Update to 2.9.0 or newer; your backups were there all along.

The server I was managing seems to have vanished after a click in the header

Before 2.9.0 the header had a Simple/Advanced toggle, and one click re-pointed the open server at the other kind - which looked exactly like the server had been deleted. Nothing was deleted or moved. On 2.9.0 the toggle is gone: how a server is run lives under Advanced in Server Settings, cannot be changed while the server is running, and asks first. If a server is pointed at the wrong kind, open Server Settings → Advanced and set it back.

The config editor saved the wrong text into a file

A bug before 2.9.0: selecting a file switched its name at once while the editor still held the previous file's text, and Save stayed enabled. 2.9.0 keeps the editor and Save off until the opened file's own text has loaded, shows a failed read with Try again, ignores late reads of a previously clicked file, and asks before switching files with unsaved edits. Update; a file that was overwritten this way has to be corrected by hand.

I want to switch the server's loader or modpack

A modpack or server type is applied when the container is created, so switch by starting over: Delete container in the Danger zone of Server Settings removes the container and keeps the server, then the create flow reappears prefilled and you pick the new type or pack. The world is kept unless you also tick Also delete its world data and type the container's name. To add a set of mods to the server you already have instead, see the next entry.

I want a different Minecraft version on my plain server

Since 2.10.0 a plain (Simple) server changes version in place - no deleting, no restoring. Stop the server, open Server Settings → Performance & network → Change version…, and pick the version. MineUI checks that your Java fits it, downloads the server for that version, backs the world up first (a normal backup, listed on the Backups page), and switches. Moving to an older version needs an extra tick, because an older Minecraft usually cannot open a world saved by a newer one. A container server is different: its version is set when the container is created, so there you delete the container (Server Settings → Danger zone → Delete container, which keeps the world unless you also tick it) and create it again with the version you want.

I have a zip of mods, not single jars

Mods → Add mod or plugin takes the .zip as it is: when the file you pick or link to is a zip, the dialog asks whether it is several mods or one. Choose several and MineUI unpacks the .jar files inside - a zipped folder of mods, or the mods folder of a server pack - installs them in one go, and lists what went in and how many other files were left out (configs are not installed). Limits: 500 jars, 256 MiB each, 2 GiB in total. A launcher modpack file (Modrinth .mrpack-style or a CurseForge export) contains no mods, only a list to download - create the server from a modpack instead; a CurseForge export goes straight into the CurseForge zip tab there.

A server made from a modpack is not up yet

Creating from a pack resolves when the container has started, not when the server inside is ready: on first boot the image downloads the pack (for a CurseForge zip, the mods its manifest lists), installs its loader and mods, and only then starts the server, which can take minutes for a large pack. Since 2.9.0 the dashboard shows Starting up… for exactly this - running but not answering yet - and turns Online when players can join; the log stream shows the Done line. Pick a Minecraft version the pack actually has a build for - the version selects the Java image, and a pack on the wrong Java does not start. A CurseForge zip takes its version from the manifest, so there is nothing to get wrong there.

My pack was made in the CurseForge app and isn't published anywhere

Export it: in the CurseForge app open the profile, choose Export profile, and keep the zip it writes (manifest.json plus an overrides folder). In MineUI's create flow choose A modpack → CurseForge zip and pick that file. Since 2.8.0 MineUI reads the pack's name, Minecraft version and loader from the manifest, copies the zip into the container before its first start, and the image downloads the listed mods and applies the overrides - no API key, and the Minecraft version is taken from the pack. Packs for Minecraft 1.16 and older are refused: the Java 8 image those versions need carries no CurseForge API key. The zip must be under 512 MB, and if creating fails at any step the half-made container is removed so you can try again.

I don't have a container to attach to

Since MineUI 2.6.0 you don't need to make one by hand: App Settings → Servers → Add server → Modded or modpack server creates an itzg/minecraft-server container for you (pick a server type or a modpack, the Minecraft version, memory, and ports) and attaches to it. The first run can take a few minutes while the runtime pulls the image. Prefer your own? Start a container whose world lives under /data - docker run -d -e EULA=TRUE -v ./data:/data -p 25565:25565 itzg/minecraft-server - then use Add server → A container I already run and enter its name, ports, and RCON password.

RCON connection refused

Check server.properties: enable-rcon=true, a non-empty rcon.password, and that rcon.port (default 25575) is reachable from the app. In Simple mode MineUI configures RCON when it creates the server, and a container created from Add server → Modded or modpack server gets a generated RCON password with RCON published on 127.0.0.1 only; for containers you attach to, you may need to set these yourself and restart the server. The connection details MineUI uses are under Advanced in Server Settings, where the RCON password can be revealed to compare. If the server is simply stopped, 2.9.0 says so on the Console, Players and Status pages and offers Start instead of a connection error.

RCON read timed out on a Forge server (say, broadcasts, restart warnings)

Before MineUI 2.6.0, a command with no output - say, and with it scheduled broadcasts and restart warnings - waited 5 s and was reported as timed out on Forge even though it ran, because Forge sends no reply packet for empty output. 2.6.0 fixes this, and also reassembles RCON output longer than 4096 bytes (large mod or player lists) that used to be cut off. Update to 2.6.0 or later.

The AppImage won't start on Linux

Make it executable first: chmod +x MineUI_2.12.0_amd64.AppImage. If it still fails, your distro may be missing FUSE (needed by all AppImages) - install libfuse2/fuse, or use the deb package instead.

The window never appears on Linux with an NVIDIA GPU (Wayland)

WebKitGTK's DMA-BUF renderer aborts on NVIDIA + Wayland before the first frame. MineUI 2.5.0 and later switch it off automatically when the NVIDIA kernel module is present. On an older build, launch with WEBKIT_DISABLE_DMABUF_RENDERER=1 in the environment.

A scheduled task didn't run

Jobs run only while MineUI is open, and a slot that passed while the app was closed is skipped rather than run late. Restart and broadcast jobs also require the server to be running (the Status page's activity log records "server not running" when they're skipped). Schedules are per server, so check the right server is open, then check the job's next-run time in Server Settings → Scheduled tasks and use Run now to test it.

Enriched metrics (tick-based TPS/MSPT, chunk/entity counts) are missing

Those come from the optional mineui_server_utils mod/plugin. Verify it's installed in the server (JDK 17 required) and that Server Settings → Advanced → Server-utils URL points at it (default http://127.0.0.1:8787 - try curl http://127.0.0.1:8787/health). If it binds a non-loopback host, MINEUI_SERVER_UTILS_TOKEN must be set or it refuses to start. Without it, MineUI falls back to server-list ping + container/process metrics.