Troubleshooting

”500 Server Error” on first load

• Check storage/logs/laravel.log for the specific error.
• Verify .env file exists and is readable.
• Ensure storage/ and bootstrap/cache/ are writable by www-data.

”SQLSTATE[HY000] [1045] Access denied”

• Double-check database credentials entered in the install wizard.
• Verify the MySQL user exists and has permissions: SHOW GRANTS FOR 'ai_edu_user'@'localhost';

”The public/storage directory does not exist”

• Run php artisan storage:link.
• If it says “link already exists”, delete public/storage first, then re-run.

”Queue worker not processing jobs”

• Check Supervisor status: supervisorctl status
• Check worker logs: tail -f /var/www/ai-education-studio/storage/logs/worker.log
• Ensure QUEUE_CONNECTION in .env is set to database.

”npm run build fails”

• Ensure Node.js 22.x is installed: node -v
• Delete node_modules and reinstall: rm -rf node_modules && npm install && npm run build

”Install wizard shows 500 error”

• Check storage/logs/laravel.log for the exact error.
• Ensure .env file is writable by the web server (www-data).

”License shows Pending after installation”

• Go to Super Admin → License and click Re-verify Now.
• Check that the license server is reachable from your server.
• Verify the license key is correct.

”License shows Invalid”

• Go to Super Admin → License and enter a new valid license key.
• Ensure the license has not expired.
• Check that the domain matches the one the license was activated for.