Reading Game Server Logs Without Drowning

Something broke. You open the log, and it is forty thousand lines of a server telling you about every player who connected since Tuesday.

Logs are where the answer already is, and they are also where most owners give up. The difference between someone who diagnoses a problem in five minutes and someone who spends an evening guessing is almost never knowledge of the game, it is knowing how to cut forty thousand lines down to the six that matter.

Where the logs are

A file in the server directory. Most games write to logs/latest.log, console.log, or a dated file in a logs folder. Look there first.

systemd's journal, if the server runs as a service:

journalctl -u mygame -n 200
journalctl -u mygame -f
journalctl -u mygame --since "1 hour ago"

This is one of the better reasons to run the server under systemd at all: the log handling is free and consistent. Keeping a game server running covers the setup.

The system log, for things that killed your process from outside: journalctl -k for kernel messages, dmesg for the same.

Your control panel's console view, which is usually the same file with a worse interface.

The four commands

Follow it live.

tail -f logs/latest.log

Run this in one window, reproduce the problem in another. Watching a failure happen in real time is worth more than reading about it afterwards, because you see the order.

Find the interesting lines.

grep -i "error\|exception\|failed\|warn" logs/latest.log

Case-insensitive, several patterns at once. This is the first cut and it usually reduces forty thousand lines to a few dozen.

See what surrounds a line.

grep -i -B 5 -A 20 "exception" logs/latest.log

Five lines before, twenty after. Context is where the cause lives — the error itself is often just the symptom announcing itself.

Look at the end.

tail -n 200 logs/latest.log

For a crash, the last two hundred lines contain it.

Read from the top, not the bottom

The most valuable habit on this page.

When something fails, it usually fails in a cascade: one thing breaks, and twenty things that depended on it break afterwards, each producing its own error. The last error is the twentieth. The first one is the cause.

So when you find a block of errors, scroll up to where they started and read forward. People routinely spend an hour investigating an error that was itself a consequence, and the actual cause was forty lines earlier saying a file could not be found.

The same applies to startup: a server that will not start usually announces the real problem early and then complains about the consequences for the rest of the file.

What each severity actually means

INFO, routine. Players joining, chunks saving, a plugin loading. Almost never useful except as a timeline.

WARN; something unexpected that was handled. Most warnings on most servers are noise, and this is the level people most often over-react to. A server producing thirty warnings a minute since installation is not thirty problems.

The warnings that do matter are the ones that are new. A warning you have never seen before, appearing on the day something broke, is a lead. A warning that has been there for six months is furniture.

ERROR, something failed. Worth reading every time.

FATAL / SEVERE — the server is stopping. This is what you are looking for after a crash.

Learning what your server's normal noise looks like is genuinely useful, and the cheapest way is to read a hundred lines of a healthy log once, while nothing is wrong. Then the abnormal is obvious.

Stack traces

Java servers: Minecraft and anything derived from it, produce these, and they look far more intimidating than they are.

java.lang.NullPointerException
 at com.example.plugin.Thing.method(Thing.java:42)
 at com.example.plugin.Other.call(Other.java:17)
 at org.bukkit.plugin.SimplePluginManager...

The first line is what went wrong. The rest is where it happened, most recent first.

The useful line is the topmost one that mentions something you installed. In the example above, com.example.plugin is the culprit. Everything below it is the server infrastructure that called into the plugin, which is not the problem.

That single rule; find the first line naming a plugin — resolves the majority of Java server crashes to a specific addon in about ten seconds.

The five things you are usually looking for

A plugin failing to load at startup. Almost always a version mismatch after an update. The log says so plainly, near the top.

A file or permission error. Permission denied, Cannot write, No such file. Usually means the server is running as a different user from the one that owns the files, the single most common cause of a server that starts and then behaves strangely. Linux basics covers ownership.

A port already in use. Address already in use means an old instance is still running. Find it and stop it before starting another.

Out of memory. Either the game saying so, or the kernel killing the process. journalctl -k | grep -i "killed process" finds the latter, and it is worth checking whenever a server dies with no explanation in its own log at all.

Disk full. Produces failures that look like anything else. df -h takes two seconds and rules it out.

What logs will not tell you

Why a server feels laggy. Logs record events, not performance. A server can log nothing unusual while playing terribly, because tick rate problems are not errors. Profiling tools, not logs.

Why players left. Nothing in a log distinguishes a player who disconnected happily from one who quit in disgust.

Network problems between you and a player. Their route is not visible from your machine. Ping and latency covers what is being measured.

Keeping them readable

Rotate them. A log file that grows forever eventually fills the disk, and a full disk breaks things in confusing ways. logrotate is standard on every Linux distribution and takes ten minutes to configure. systemd's journal rotates by default, with a size cap you can set.

Keep enough history to be useful. A week minimum. When a player reports something that happened on Saturday, a log that only covers today is no help.

Do not raise the log level for fun. Debug logging is enormously verbose and turns a readable file into an unreadable one. Turn it on for a specific investigation, then turn it off.

Save the log before you restart. The single most common self-inflicted wound in diagnosis: a server crashes, the owner restarts it immediately, and the log is overwritten by the new session. Copy it somewhere first: it takes two seconds and it is the evidence.

Logs as a moderation record

The other half of what logs are for, and the half that gets configured last.

Every dispute in a community reduces to "what happened", and the log is the only impartial answer. This matters most in modes where the rules are social rather than mechanical, TTT, jailbreak, DarkRP — where an admin adjudicating an incident is otherwise choosing between two accounts.

Chat logs resolve most harassment reports in seconds.

Damage and kill logs resolve most accusations of rule-breaking. Many gamemode plugins produce a per-round damage report specifically for this.

Connection logs; who was on, when, from where, resolve alt-account and ban-evasion questions. Ban evasion and alt detection covers the wider problem.

Admin action logs resolve disputes about the moderation itself, which are the ones that damage a community most when unresolved.

Two practical points. Keep them long enough: a report arrives days after the incident, and a log covering only today is useless. And know where they are before you need them, because searching for the right file while a community argument is running is the worst time to learn your logging setup.

Player support without a helpdesk covers building a process around this; the logging is the part that makes the process possible.

The habit worth building

Read your log for two minutes a week when nothing is wrong.

This sounds pointless and is the single most useful logging habit available. You learn what normal looks like, which means abnormal becomes obvious. You notice the warning that started appearing last Tuesday. You catch the plugin that has been silently failing to load since an update, on a server that otherwise seems fine.

Most of the problems that eventually become emergencies were visible in the log for weeks first. Nobody was reading it.

Putting it together

When something breaks, in order:

1. df -h — disk space, free to rule out
2. Copy the current log somewhere safe
3. grep -i "error\|exception\|fatal" for the first cut
4. Scroll up to where the errors started
5. Find the topmost line naming something you installed
6. journalctl -k | grep -i killed if the log ends with no explanation

That method covers most of what goes wrong, and the cases it does not cover are the ones worth reading diagnosing a server crash for.