Troubleshooting

When encountering errors, check this guide for common causes and resolutions.

Checking Panel LogsCopy Anchor Link

Aquadactyl logs Laravel exceptions and application errors to /var/www/aquadactyl/storage/logs/:

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

502 Bad GatewayCopy Anchor Link

A 502 Bad Gateway error indicates Nginx cannot communicate with PHP-FPM.

1. Verify PHP-FPM is running:

   Copy Text

   sudo systemctl status php8.5-fpm

2. Verify socket path: Ensure the socket in /etc/nginx/sites-available/aquadactyl.conf matches your installed PHP version:

   Copy Text

   fastcgi_pass unix:/run/php/php8.5-fpm.sock;

3. Check socket permissions:

   Copy Text

   ls -la /run/php/php8.5-fpm.sock

Permission & Ownership ErrorsCopy Anchor Link

Aquadactyl enforces a strict permission model: source files are owned by root:www-data (mode 0750 for directories, 0640 for files), while only storage/ and bootstrap/cache/ are writable by the web user.

To restore proper permissions without breaking security:

curl -fsSL https://raw.githubusercontent.com/Aquadactyl/Installer/main/deploy.sh | sudo bash -s -- permissions

CSRF Token Mismatch / Login LoopCopy Anchor Link

If logging in redirects you immediately back to the login page without an error:

1. Check APP_URL: Verify APP_URL in .env matches the exact URL in your browser, including https://.
2. Cookie security: If testing over plain HTTP locally, set:

   Copy Text

   SESSION_SECURE_COOKIE=false

3. Clear session cookies and panel cache:

   Copy Text

   sudo -u www-data php artisan config:clear
   sudo -u www-data php artisan cache:clear

Queue Worker IssuesCopy Anchor Link

If server installations, emails, or user account emails are never sent:

1. Inspect worker logs:

   Copy Text

   journalctl -u aquaq.service -f

2. Restart worker:

   Copy Text

   sudo systemctl restart aquaq.service

3. Check Redis:

   Copy Text

   redis-cli ping

Blueprint Extension ErrorsCopy Anchor Link

If installing a Blueprint extension fails:

1. Verify that [email protected] and node 24 are installed and available in PATH.
2. Clean build cache:

   Copy Text

   cd /var/www/aquadactyl
   sudo pnpm store prune
   sudo -u www-data php artisan view:clear

3. Run the Blueprint repair/rebuild command:

   Copy Text

   sudo blueprint -build