When a game server won't start, fails to install, or behaves unexpectedly, GameCP gives you three tools to figure out what's going wrong: the Terminal, the Log Viewer, and the AI Debugger.

This guide walks you through each tool and when to use them.

Accessing Debug Tools

All three debugging tools are accessible from the Action Overlay on any game server card. Click or tap on a server card to open the overlay, where you'll see:

Terminal — live console output
Logs — structured log viewer with history
AI Debug — AI-powered log analysis

Tool 1: Terminal (Live Console)

The Terminal shows the live output from your game server's Docker container, exactly like running docker logs -f on the server.

When to Use

Your server status shows Running but you can't connect
You want to watch the game server boot in real time
You need to see error messages as they happen

How to Use

Open the Action Overlay on your server card
Click Terminal
Watch the live output as it streams in

The terminal shows standard output (stdout) and error output (stderr) from the game process. Look for lines containing ERROR, WARN, FATAL, or Exception — these are usually the clues.

Common Patterns

Port already in use — another process or server is using the same port
Missing file or directory — the game files may not have installed completely
Permission denied — file ownership issue on the node
Out of memory — the server needs more RAM (check Docker resource limits)

Tool 2: Log Viewer (Command History)

The Log Viewer is different from the terminal — it shows structured logs from GameCP itself, recording every command and script that runs during installation, startup, and shutdown.

When to Use

Installation failed and you want to see what step broke
Server won't start and you want to see the exact startup commands
You want to review what scripts ran and in what order

How to Use

Open the Action Overlay on your server card
Click Logs
The full-screen log viewer opens

Understanding the Log Viewer

The logs are organized by execution groups — each time a server installs, starts, or stops, it creates a new group. Each group shows:

Setup phase — preparation commands (creating directories, setting permissions)
Content phase — the main action (downloading game files, running the startup command)
Console phase — output from the game process itself
Result phase — the final outcome (success, failure, exit code)

You can switch between these phases using the tabs at the top of each execution group.

Log Levels

Logs are color-coded by severity:

Debug — detailed internal information (usually safe to ignore)
Info — normal operations and progress updates
Warn — something unexpected but not fatal
Error — something went wrong
Fatal — critical failure that stopped the process

Code Blocks in Logs

When GameCP runs a script or command, the log viewer renders it as a formatted code block showing:

The command that was executed
The language or type of script
The file path where the script lives on disk

This makes it easy to see exactly what ran and copy commands for manual testing on the node.

Filtering and Search

Use the toolbar at the top to:

Search — filter logs by keyword (e.g., search for "error" or a specific file name)
Log level filter — show only errors, warnings, or specific levels
Date range — narrow down to a specific time window
Download — export logs as a text file for sharing or deeper analysis

Tool 3: AI Debugger

The AI Debugger uses Google Gemini to analyze your server's logs and provide a diagnosis with actionable recommendations.

When to Use

You've checked the terminal and logs but can't figure out the problem
You want a quick summary of what went wrong
The error messages are unfamiliar or complex

How to Use

Open the Action Overlay on your server card
Click AI Debug
Choose the debug type:
- Installation — analyzes installation logs
- Startup — analyzes startup logs
Click Analyze and wait for the response

What You Get

The AI Debugger provides three sections:

Diagnosis — what went wrong and why
Recommendations — step-by-step actions to fix the issue
Technical Details — deeper technical context, relevant config, and commands to try

The response streams in real-time and includes formatted code blocks you can copy directly.

Limits

The AI Debugger is rate-limited to 10 analyses per hour to manage costs. Use the terminal and log viewer first for quick checks, and save AI debug for when you're stuck.

Debugging Workflow

Here's the recommended order when something goes wrong:

Check the Terminal first — look for obvious errors in the live output
Open the Log Viewer — find the specific execution group that failed, check the result phase for exit codes
Run AI Debug — if you're stuck, let the AI analyze the logs and suggest fixes
Check the Node — if the issue seems infrastructure-related (disk space, network, permissions), refer to the Node Troubleshooting tutorial

Tips

The Log Viewer persists history even after restarts — you can always go back and review past installations or startups
If installation logs show a download failure, it's usually a network issue on the node (check DNS, firewall, internet connectivity)
Startup errors that mention "EADDRINUSE" mean a port conflict — check if another server is using the same port
The AI Debugger works best when there are recent logs to analyze — trigger a start or install attempt before running it