Something broke?
Work from the symptom to the likely cause and first useful check.
Start with the failing layer#
Ask one question first: What is the earliest step that no longer works? Power and boot come before ZimaOS; ZimaOS comes before Crafty; Crafty comes before Minecraft; LAN comes before Playit or port forwarding. Fix that earliest failing layer.
My USB will not boot
Usually means: the image was copied rather than flashed, the wrong boot entry was selected, or UEFI/Secure Boot blocks it.
First check: does Etcher show a successful verification?
Fix: reflash the official .img, use the one-time boot menu, choose the UEFI USB entry, and follow current ZimaOS guidance for Secure Boot.
Ask for help with: PC model, USB model, boot-menu photo and exact image filename.
ZimaOS will not install or open
First check: target drive model/capacity, Ethernet lights and the IP on the local monitor.
Fix: disconnect extra drives, retry the verified USB, then place the viewing device on the same non-guest network. Type the numeric http:// address.
Ask with: PC/storage model, installer screen, ZimaOS version and network layout.
Crafty will not open or keeps restarting
Usually means: wrong HTTPS port, self-signed certificate not accepted locally, port conflict, bad path or permissions.
First check: ZimaOS app status and the first error in the container log.
Fix: use the exact app URL, confirm persistent paths exist and no other app owns the mapped port.
Server does not start
First check: the first error before “process exited.”
Fix: accept the EULA through Crafty, match Java to Minecraft, remove the last new mod, check dependencies, free disk space and confirm port 25565 is unused.
Ask with: Minecraft, Loader, Java, full mod list and complete log—not a cropped final line.
Mods are not loading
Confirm Fabric—not Forge—versions, correct game patch, Fabric API and named dependencies. Remove client-only mods from the server. If the mods folder is missing, start the Fabric server once and verify you are editing the active server directory.
LAN joining fails
Wait for Done, use the numeric ZimaOS LAN IP and correct port, match client version/mods, and leave guest Wi-Fi. “Connection refused” suggests no listener; “timed out” suggests traffic did not reach it.
Friends cannot join
Do not touch public settings until LAN works. For Playit, confirm agent online and local target. For forwarding, confirm the reservation, TCP 25565, public-vs-private IP, CGNAT and outside-network testing.
High ping or server lag
High ping is network delay; low TPS is slow game logic. Ask whether everyone is affected, inspect TPS/MSPT, one-core CPU, disk space and recent mods, then reduce simulation distance and entity load.
World corruption or failed restore
Stop immediately and preserve the current folder. Restore the latest verified backup to a test server first. Do not repeatedly open the same world in different Minecraft versions.
Disk full, permission denied or upload fails
Delete only known disposable logs/old backups after copying what matters. Check ZimaOS free space and Crafty’s mounted path. A container can see only mounted, writable directories; changing random ownership values can make the problem worse.
Whitelist or authentication blocks a player
Check exact Java username spelling, online-mode=true, Microsoft/Mojang service availability and whitelist list. Add the player again while the server is online.
Before asking someone else#
Record what last worked, what changed, exact versions and the full relevant log. Continue to the support-template chapter and remove public IPs, tokens and passwords before posting.