Troubleshooting

Solutions to common problems you may encounter when running Timecrack.

Blank Page / 500 Error

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

  • Laravel Log — Check storage/logs/laravel.log for detailed error messages.
  • Storage Permissions — The storage/ and bootstrap/cache/ directories must be writable by the web server.
  • PHP Version — Verify that PHP 8.2 or newer is installed: php -v
  • .env Configuration — Ensure the .env file exists and contains valid settings, including APP_KEY.
# Fix storage permissions
sudo chmod -R 775 storage bootstrap/cache
sudo chown -R www-data:www-data storage bootstrap/cache

# Regenerate the application key if missing
php artisan key:generate

Database Connection Failed

If Timecrack cannot connect to the database:

  • Verify your database credentials in the .env file (DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD)
  • Ensure the MySQL server is running: sudo systemctl status mysql
  • Check that the database exists and the user has the required privileges
  • Test the connection manually from the command line
# Test MySQL connection
mysql -u your_db_user -p -h 127.0.0.1 timecrack

Cache Issues

Stale cache can cause unexpected behavior after updates or configuration changes. Clear all caches with:

php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear

# Or clear everything at once
php artisan optimize:clear

URL Rewriting Not Working

If you get 404 errors when navigating Timecrack:

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

Artisan Commands for Debugging

Laravel's Artisan CLI provides several helpful commands for diagnosing issues:

# Check the application environment
php artisan env

# List all registered routes
php artisan route:list

# Test the database connection
php artisan db:show

# Run migrations status check
php artisan migrate:status

Log Files

Timecrack stores application logs in the storage/logs/ directory. Key log files to check:

  • storage/logs/laravel.log — Main application log with errors, warnings, and debug info
  • /var/log/apache2/error.log or /var/log/nginx/error.log — Web server error logs
  • /var/log/mysql/error.log — MySQL server error log

Tip: Set APP_DEBUG=true in your .env file temporarily to get detailed error pages in the browser. Remember to set it back to false in production.

Performance Issues

If Timecrack feels slow:

  • Enable PHP OPcache for faster script execution
  • Cache configuration and routes: php artisan optimize
  • Ensure your MySQL server has adequate resources and indexes are up to date
  • Check server resource usage (top, htop)

Still Need Help?

If the above solutions don't resolve your issue:

  • Search existing GitHub Issues
  • Open a new issue with your error logs and environment details