Troubleshooting

Solutions to common problems you may encounter when running Apphold.

Blank Page / 500 Error

If you see a blank page or a 500 Internal Server Error, check the following:

  • PHP Error Logs — Check your server's PHP error log for detailed error messages. On most servers this is located at /var/log/php/error.log or /var/log/apache2/error.log.
  • File Permissions — Ensure the web server can read all files and write to the necessary directories.
  • PHP Version — Verify that PHP 8.2 or newer is installed: php -v
  • Required Extensions — Check that all required PHP extensions are enabled.
# Check installed PHP extensions
php -m | grep -E 'mbstring|pdo|json|openssl'

Database Connection Failed

If Apphold cannot connect to the database:

  • Verify that your database credentials in the configuration file are correct
  • Ensure the database server is running
  • Check that the database user has sufficient privileges
  • If using MySQL, verify the host and port are correct
# Test MySQL connection
mysql -u username -p -h localhost apphold_db

URL Rewriting Not Working

If you get 404 errors when navigating Apphold:

Apache

  • Ensure mod_rewrite is enabled: sudo a2enmod rewrite
  • Verify AllowOverride All is set in your virtual host configuration
  • Restart Apache after changes: sudo systemctl restart apache2

Nginx

  • Ensure your try_files directive is configured correctly
  • Reload Nginx after changes: sudo systemctl reload nginx

Data Not Recording

If telemetry data or uptime checks fail to record:

  • Check that the database is accessible and has sufficient disk space
  • Verify that the scheduled task runner (cron) is configured correctly
  • Check browser console for JavaScript errors
  • Ensure you haven't exceeded any PHP upload or post size limits

Monitors Not Running

Apphold's uptime monitoring requires a properly configured scheduler:

  • Cron Job — Ensure the Laravel scheduler is running: * * * * * cd /var/www/apphold && php artisan schedule:run >> /dev/null 2>&1
  • Queue Worker — Verify the queue worker is active for processing monitor checks
  • Check the application logs at storage/logs/laravel.log for errors

Performance Issues

If Apphold feels slow:

  • Enable PHP OPcache for faster script execution
  • Ensure your database server has adequate resources
  • Consider optimizing the number of concurrent monitors and check intervals
  • Check server resource usage (top, htop)

Still Need Help?

If the above solutions don't resolve your issue: