Řešení častých chyb Pterodactylu – 500, nedostupný Wings, CORS

Většina problémů s Pterodactylem spadá do několika opakujících se kategorií. Než začnete cokoli přeinstalovávat, projděte si tento přehled – ke každé chybě je postup, kde hledat a co obvykle pomůže.

Kde hledat logy

Komponenta	Log
Panel (Laravel)	/var/www/pterodactyl/storage/logs/laravel-YYYY-MM-DD.log
nginx	/var/log/nginx/error.log
Queue worker	journalctl -u pteroq -n 100
Wings	journalctl -u wings -n 200 nebo /var/log/pterodactyl/wings.log
Instalace serveru	/var/log/pterodactyl/install/<uuid>.log na nodu

Pterodactyl umí také vygenerovat odkaz na diagnostický výpis Wings:

sudo wings diagnostics

Před sdílením výstupu kdekoli veřejně zkontrolujte, že neobsahuje tokeny.

Chyba 500 v Panelu

Hláška „An unexpected error was encountered“ je obecná, skutečná příčina je v Laravel logu:

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

Nejčastější příčiny:

• Práva souborů – Laravel nemůže zapisovat do storage nebo bootstrap/cache: bash cd /var/www/pterodactyl sudo chown -R www-data:www-data /var/www/pterodactyl/* sudo chmod -R 755 storage/* bootstrap/cache/
• Databáze – špatné heslo v .env nebo neběžící MariaDB (SQLSTATE[HY000] [2002]). Ověřte systemctl status mariadb.
• Redis neběží – Connection refused u portu 6379. sudo systemctl enable --now redis-server.
• Nedokončená aktualizace – chybějící migrace (Base table or view not found). Spusťte php artisan migrate --seed --force.
• Zastaralá cache konfigurace po úpravě .env: bash php artisan config:clear php artisan view:clear

Červené srdíčko – Panel nevidí Wings

Srdíčko v seznamu nodů se kontroluje z vašeho prohlížeče, ne ze serveru Panelu. Postupujte od nejjednoduššího:

1. Běží Wings? systemctl status wings. Pokud padá, spusťte ručně sudo wings --debug a čtěte chybu.
2. Je port otevřený? Z vlastního počítače: curl -v https://node1.example.cz:8080. Timeout = firewall (ufw, firewall providera, bezpečnostní skupina).
3. Sedí SSL? Panel na HTTPS vyžaduje SSL i na Wings. V Panelu u nodu „Use SSL Connection“ a ve config.yml api.ssl.enabled: true s platnými cestami k certifikátu.
4. Sedí FQDN? Doména v nastavení nodu musí odpovídat certifikátu.
5. Cloudflare proxy? Oranžový mráček na doméně nodu port 8080 nepropustí. Přepněte na DNS only.
6. Sedí token? Pokud jste node v Panelu smazali a vytvořili znovu, starý config.yml už neplatí. Vygenerujte konfiguraci znovu.

Websocket a CORS chyby

V konzoli serveru se objeví „Connection to websocket failed“ nebo v nástrojích prohlížeče (F12 → Console) hláška o CORS. Příčiny:

• Mixed content – Panel HTTPS, Wings HTTP. Řešení v článku SSL pro Panel i Wings.
• Nesouhlasí URL Panelu – APP_URL v .env musí přesně odpovídat adrese, ze které Panel otevíráte (včetně https:// a bez lomítka na konci). Hodnota remote ve Wings config.yml musí ukazovat na stejnou adresu.
• Panel na více doménách – Wings povoluje jen původ odpovídající remote. Další domény přidejte do allowed_origins v config.yml: ```yaml allowed_origins:
  • https://panel2.example.cz ``` a restartujte Wings.

Po změně APP_URL nezapomeňte php artisan config:clear.

Server se zasekl při instalaci

Server zůstává ve stavu „Installing“ a nic se neděje:

• Neběží queue worker – systemctl status pteroq. Bez něj se úloha instalace na node vůbec neodešle.
• Instalační skript selhal – přečtěte install log na nodu. Typicky nefunkční URL ke stažení nebo chyba v eggu.
• Docker neumí stáhnout image – zkuste ručně docker pull ghcr.io/pterodactyl/yolks:java_21.

Instalaci lze spustit znovu v administraci u serveru: Manage → Reinstall Server.

Server se nespustí / hned spadne

• Out of memory – kontejner dosáhl limitu RAM. Zkontrolujte, že -Xmx (u Javy) je nižší než přidělená paměť, JVM potřebuje paměť i mimo heap.
• Špatná verze Javy – „UnsupportedClassVersionError“ znamená starou Javu. Vyberte novější Docker image v záložce Startup.
• Disk plný – df -h /var/lib/pterodactyl.

SFTP nefunguje

• Port je 2022, ne 22. V klientovi (FileZilla, WinSCP) nastavte protokol SFTP a port 2022.
• Uživatelské jméno má tvar uzivatel.xxxxxxxx – přesný údaj najdete v záložce Settings serveru.
• Heslo je heslo k účtu v Panelu.

Postup, když nevíte kde začít

1. systemctl status nginx php8.3-fpm mariadb redis-server pteroq na Panelu (verzi PHP upravte podle sebe).
2. systemctl status docker wings na nodu.
3. Poslední řádky Laravel logu a logu Wings.

Výstup těchto příkazů je přesně to, co se hodí vložit do ColdHost AI v režimu Řešení problémů – z logu obvykle rychle pozná, která z výše uvedených příčin platí.