Skip to content
CatalystCatalyst Docs

Server Issues

Prerequisites

Section titled “Prerequisites”
  • Access to the game server as its owner or as a subuser with the permissions the fix needs (console, power, files, startup).
  • For node-level causes (full disk, OOM killer), an administrator for the node that hosts the server.

Crash loop (starts, then stops)

Section titled “Crash loop (starts, then stops)”
  1. Open the server’s Console tab and press Start — the first error after start is the cause; everything after is fallout.
  2. Usual suspects in order:
    • A config or startup variable you just changed → revert it (startup).
    • A new/updated mod or plugin → remove it and restart (mods).
    • Minecraft shows a Minecraft EULA prompt → select I Agree, then start again.
    • Out of memory → the game asked for more than the server owns; lower the game’s memory setting or raise the server limit.
  3. If nothing changed and it suddenly loops, check whether the node is unhealthy (node issues) — full disks and OOM killers look like game crashes.

Stuck “starting” or “stopping”

Section titled “Stuck “starting” or “stopping””
  1. Wait 60–90 seconds; large worlds save slowly.
  2. Use Kill if Stop hangs, then Start again (power controls).
  3. Repeated hangs on stop point at a mod blocking shutdown — remove suspects one by one.

Port already in use

Section titled “Port already in use”

Two servers claim the same allocation, or a killed server did not release its port. The panel rejects the change with PORT_ALREADY_IN_USE (“Port N is already in use on this node”). Confirm no other server uses that IP + port (networking), kill any ghost process via the node, and restart. If it persists, the administrator must free the allocation.

Files tab hangs, times out, or returns empty files

Section titled “Files tab hangs, times out, or returns empty files”

Every listing, download and upload in the Files tab is relayed by the panel to the node agent, so the failure is usually the node rather than the file:

  • “The node is offline and cannot accept this action.” (NODE_OFFLINE) — see node issues.
  • “The agent did not respond in time.” (AGENT_TIMEOUT) — retry once, then check the node’s load and free disk.
  • “The file tunnel is busy. Please try again later.” (FILE_TUNNEL_BUSY) — too many file operations are queued for that node; wait for in-flight transfers to finish.

If the node is healthy, check the panel version: listings that timed out without a node error were fixed in v1.79.4, and files that opened or downloaded empty were fixed in v1.81.0. Update the panel (updating Catalyst).

Lag with normal-looking settings

Section titled “Lag with normal-looking settings”
  1. Check Metrics: memory pressure, CPU saturation, or disk latency.
  2. Reduce view distance / loaded chunks / entity counts before buying bigger limits.
  3. Rule out the network path (networking issues) — server TPS fine + players rubber-banding means transit, not the server.

Nuclear option

Section titled “Nuclear option”

When the install itself is damaged: back up, then reinstall. Faster than archaeology for mangled installs.

Section titled “Related”