Troubleshooting

Reading Error Logs

When the Panel shows an unexpected error, the first thing to check is its log. This command shows the last 100 lines of today's log:

tail -n 100 /var/www/pterodactyl/storage/logs/laravel-$(date +%F).log

Finding the Error

Each error in the log starts with a line that has the date and time in brackets, followed by a long stack trace. The line with the date is the one that describes the problem, for example:

[2026-09-29 10:15:02] production.ERROR: file_put_contents(/var/www/pterodactyl/storage/framework/views/...): Failed to open stream: Permission denied

This error means the web server cannot write to the storage directory, which usually means the file permissions are wrong. You may ignore the stack trace below the line when looking for the cause.

To show only these lines, without the stack traces, run:

tail -n 1000 /var/www/pterodactyl/storage/logs/laravel-$(date +%F).log | grep "\[$(date +%Y)"

When you ask for help, include these lines. Remove any passwords or keys first.

The Panel Shows a Blank Page

If the Panel loads but shows a blank page, open your browser's developer console to see the error.

An extension can stop the Panel's pages from loading. To check, set PTERODACTYL_EXTENSIONS_ENABLED=false in your .env file, run php artisan config:clear, and reload the page. If the Panel works again, find the extension that causes the problem with php artisan p:extension:list, and disable it with php artisan p:extension:disable. See Extensions.

Cannot Connect to a Server

If the Panel cannot connect to a server, work through these checks.

Basic Checks

• Wings is running. Check it with systemctl status wings.
• The browser shows no errors. Open the developer console and look for red errors.
• The node's configuration matches. Wings' /etc/pterodactyl/config.yml must match the configuration shown under Admin → Nodes, on the node's Configuration tab.
• The firewall allows Wings' ports. Wings uses port 8080 or 8443 for HTTP(S), and 2022 for SFTP.
• No ad blocker is blocking the Panel or Wings.
• The Panel can reach Wings. Run curl https://node.example.com:8080 on the Panel's server, using your node's domain.
• The Panel and Wings use the same scheme. If the Panel uses HTTPS, Wings must use HTTPS too.
• Certificates are valid. If Wings uses HTTPS, check that its certificate has not expired.

Advanced Checks

• Run Wings in debug mode. Stop Wings and run wings --debug to see its errors directly. If you need help, ask on Discord.
• Check DNS. Use dig or nslookup to confirm that your domains point to the right addresses.
• Check Cloudflare. If you use Cloudflare, turn off its proxy (the orange cloud) for your Wings domain.
• Check NAT. If Wings is behind a firewall, such as pfSense, make sure the correct ports are forwarded to it.
• Add host entries. When the Panel and Wings run on one server, it can help to add an /etc/hosts entry that points the Panel's domain at the server.

Invalid MAC Exception

The error appears in the log as an invalid MAC when decrypting. The only fix is to restore the original APP_KEY in your .env file. If the original key is lost, the encrypted data cannot be recovered.

Servers Have No Internet Access

This is usually a DNS problem. By default, Wings gives containers the DNS servers 1.1.1.1 and 1.0.0.1. Some hosts block them.

To find the DNS servers your host uses, try these commands:

# NetworkManager
nmcli -g ip4.dns,ip6.dns dev show

# systemd-resolved (recent Ubuntu versions)
resolvectl status

You may also look in /etc/resolv.conf or /etc/network/interfaces.

If your host uses different DNS servers, replace 1.1.1.1 and 1.0.0.1 in Wings' /etc/pterodactyl/config.yml with them. Put IPv6 addresses in the IPv6 section. Then restart Wings.

Schedules Do Not Run

Work through these checks:

• Check the queue worker's log with journalctl -xeu pteroq, and restart it with systemctl restart pteroq.
• Clear the scheduler's cache with php /var/www/pterodactyl/artisan schedule:clear-cache.
• Check the cron entry. Run crontab -l as root, and check that the scheduler line from Getting Started is there.
• Check PHP. Run php -v and compare it with the requirements.
• Test the schedule on its own. Make its first task something that shows up in the console, such as say test on a Minecraft server. This tells you whether the problem is the schedule or its tasks.
• Check the time zones. Schedules that run at the wrong time usually mean mismatched time zones. Compare the system's (timedatectl), the Panel's (APP_TIMEZONE in .env), and Wings' (timezone in config.yml).
• Check the database and Redis. Run systemctl status mariadb and systemctl status redis-server. If either is not running, check its log with journalctl -xeu.
• Check the Panel's log, as described in Reading Error Logs.