Debugging Wings

Tools and techniques for debugging Pterodactyl Wings

This guide covers debugging tools and techniques for troubleshooting Pterodactyl Wings issues.

Debug Mode

Enabling Debug Mode

Wings supports debug mode which increases log verbosity to help diagnose issues.

Via command-line flag:

wings --debug

Via configuration file:

Edit /etc/pterodactyl/config.yml:

debug: true

Via systemd service:

Edit /etc/systemd/system/wings.service:

[Service]
ExecStart=/usr/local/bin/wings --debug

Then reload and restart:

systemctl daemon-reload
systemctl restart wings

The --debug flag takes precedence over the configuration file setting. When enabled via flag, Wings will not save the debug state to disk to prevent always running in debug mode after restart.

Debug Mode Output

When debug mode is enabled, Wings will:

• Log at DEBUG level instead of INFO level (configured in cmd/root.go:428-431)
• Print “running in debug mode” on startup (cmd/root.go:95)
• Include detailed information about:
  • Configuration loading
  • Directory creation
  • Server bootstrapping
  • Docker operations
  • Resource polling
  • State changes

Example debug output:

DEBUG running in debug mode
INFO  loading configuration from file config_file=/etc/pterodactyl/config.yml
DEBUG ensuring root data directory exists path=/var/lib/pterodactyl
DEBUG ensuring server data directory exists path=/var/lib/pterodactyl/volumes
DEBUG re-syncing server configuration for already running server

Log Files

Log Locations

Wings writes logs to multiple locations depending on configuration.

Primary Wings log:

/var/log/pterodactyl/wings.log

Installation logs (per-server):

/var/log/pterodactyl/install/<server-uuid>.log

Custom log directory:

Configure in config.yml:

system:
  log_directory: /var/log/pterodactyl

Viewing Logs

Tail the main Wings log:

tail -f /var/log/pterodactyl/wings.log

View with systemd journal:

# Follow logs in real-time
journalctl -u wings -f

# Show last 100 lines
journalctl -u wings -n 100 --no-pager

# Show logs since boot
journalctl -u wings -b

# Show logs from specific date
journalctl -u wings --since "2026-03-01"

# Show logs with specific priority
journalctl -u wings -p err

Filter logs by keyword:

grep -i "error" /var/log/pterodactyl/wings.log
grep -i "docker" /var/log/pterodactyl/wings.log
grep -i "server" /var/log/pterodactyl/wings.log | grep <server-uuid>

Log Rotation

Wings automatically configures log rotation if /etc/logrotate.d exists (see config/config.go:695-737).

Default rotation settings:

• Rotate when log reaches 10M
• Keep logs for 7 days
• Compress old logs
• Use HUP signal to reload Wings

Manual rotation:

logrotate -f /etc/logrotate.d/wings

Check rotation status:

cat /var/lib/logrotate/status | grep wings

Disable automatic log rotation in config.yml:

system:
  enable_log_rotate: false

Diagnostics Command

Wings includes a built-in diagnostics command that collects system information for troubleshooting.

Running Diagnostics

wings diagnostics

The diagnostics command will:

1. Ask if you want to include endpoints (FQDNs/IPs)
2. Ask if you want to include logs
3. Ask if you want to review before uploading
4. Collect system information
5. Optionally upload to a hastebin service

Diagnostics Output

The diagnostics report includes:

Version Information:

• Wings version
• Docker version
• Kernel version
• Operating system

Wings Configuration:

• Panel location (redacted by default)
• Webserver settings (host, port, SSL)
• SFTP server settings
• Directory paths
• System user
• Timezone
• Debug mode status

Docker Information:

• Server version
• Storage driver and status
• Logging driver
• Cgroup driver
• System warnings

Running Containers:

• List of all Docker containers

Logs:

• Last 200 lines of Wings logs (configurable)

Diagnostics Options

Custom hastebin URL:

wings diagnostics --hastebin-url https://paste.example.com

Custom log line count:

wings diagnostics --log-lines 500

Example output:

Pterodactyl Wings - Diagnostics Report
|
| Versions
| ------------------------------
               Wings: v1.11.0
              Docker: 24.0.7
              Kernel: 5.15.0-89-generic
                  OS: Ubuntu 22.04.3 LTS

| Wings Configuration
| ------------------------------
      Panel Location: {redacted}
  Internal Webserver: 0.0.0.0 : 8080
         SSL Enabled: true

Performance Profiling

Wings includes built-in support for Go’s pprof profiler to diagnose performance issues.

Enabling pprof

Start Wings with profiling:

wings --pprof

Custom pprof port:

wings --pprof --pprof-port 6060

Enable block profiling:

wings --pprof --pprof-block-rate 1

By default, pprof binds to localhost:6060 (configured in cmd/root.go:81-83).

Accessing pprof

Once enabled, pprof provides several endpoints:

CPU Profile:

go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30

Heap Memory:

go tool pprof http://localhost:6060/debug/pprof/heap

Goroutines:

go tool pprof http://localhost:6060/debug/pprof/goroutine

Block Profile:

go tool pprof http://localhost:6060/debug/pprof/block

Mutex Profile:

go tool pprof http://localhost:6060/debug/pprof/mutex

All available profiles:

curl http://localhost:6060/debug/pprof/

Analyzing Profiles

Interactive mode:

go tool pprof http://localhost:6060/debug/pprof/heap
(pprof) top10
(pprof) list functionName
(pprof) web

Generate CPU profile:

# Collect 30 seconds of CPU profiling
curl http://localhost:6060/debug/pprof/profile?seconds=30 > cpu.prof

# Analyze
go tool pprof cpu.prof

Generate SVG graph:

go tool pprof -svg http://localhost:6060/debug/pprof/heap > heap.svg

Only enable pprof when actively debugging performance issues, as it adds overhead. The profiler only binds to localhost by default for security.

Diagnostic Commands

Check Wings Status

# Systemd status
systemctl status wings

# Process information
ps aux | grep wings

# Network listeners
netstat -tlnp | grep wings
ss -tlnp | grep wings

Check Docker Status

# Docker daemon status
systemctl status docker

# Docker information
docker info
docker version

# Pterodactyl network
docker network inspect pterodactyl_nw

# Container list
docker ps -a

# Container logs
docker logs <container-id>

# Container resource usage
docker stats

Check Server States

# View saved server states
cat /var/lib/pterodactyl/states.json | jq

# Check server container
docker inspect <server-uuid>

# Check server files
ls -la /var/lib/pterodactyl/volumes/<server-uuid>/

Check Disk Usage

# Overall disk usage
df -h

# Docker disk usage
docker system df
docker system df -v

# Server directory sizes
du -sh /var/lib/pterodactyl/volumes/*

# Check inode usage
df -i

Network Diagnostics

# Check Wings API
curl -k https://localhost:8080/api/system

# Check SFTP port
telnet localhost 2022

# Check Panel connectivity
curl -I https://panel.example.com

# Check firewall
ufw status verbose
iptables -L -n -v

Common Log Messages

Startup Messages

Successful startup:

INFO  loading configuration from file
INFO  configured wings with system timezone
INFO  configured system user successfully
INFO  finished loading configuration for server
INFO  sftp server listening for connections
INFO  configuring internal webserver

Docker configuration:

INFO  creating missing pterodactyl0 interface, this could take a few seconds...
DEBUG ensuring root data directory exists
DEBUG ensuring server data directory exists

Error Messages

Configuration errors:

FATAL failed to detect system timezone or use supplied configuration value
FATAL failed to configure system directories for pterodactyl
FATAL failed to create pterodactyl system user
FATAL failed to configure docker environment

Server errors:

ERROR could create base environment for server...
ERROR error checking server environment status
WARN  failed to return server to running state
WARN  failed to attach to running server environment

Docker errors:

WARN  error while processing Docker stats output for container
DEBUG io.EOF encountered during stats decode, stopping polling...
DEBUG process in offline state while resource polling is still active

Crash Detection Messages

---------- Detected server process in a crashed state! ----------
Exit code: 1
Out of memory: false
Aborting automatic restart, last crash occurred less than 60 seconds ago.

Debugging Server Issues

Server Won’t Start

1. Check server logs:

   docker logs <server-uuid>
   

2. Check Wings logs:

   journalctl -u wings -n 100 | grep <server-uuid>
   

3. Inspect container:

   docker inspect <server-uuid>
   

4. Check for resource limits: Look for memory/CPU constraints in the server configuration.

5. Verify image exists:

   docker images | grep <image-name>
   

Server Crashes Repeatedly

Wings has built-in crash detection with a configurable timeout (default: 60 seconds in config/config.go:270).

Check crash configuration:

system:
  crash_detection:
    enabled: true
    detect_clean_exit_as_crash: true
    timeout: 60

View crash messages:

journalctl -u wings | grep "crashed state"

Resource Usage Issues

Wings polls Docker stats continuously when a server is running (see environment/docker/stats.go).

Monitor in real-time:

docker stats <server-uuid>

Check memory calculation: Wings calculates memory differently than docker stats to match the Panel display. See environment/docker/stats.go:98-120 for details.

See Also

• Common Issues - Frequently encountered problems
• Performance Tuning - Optimize Wings performance
• Wings Configuration - Complete configuration reference