Installation Issues

500 Internal Server Error

Solutions:

1. Set correct permissions:
   Terminal

   chmod -R 755 storage bootstrap/cache
   chown -R www-data:www-data storage bootstrap/cache

2. Check Laravel logs:

   Open storage/logs/laravel.log for specific error messages

3. Verify PHP version:
   Terminal

   php -v
   # Must be PHP 8.2 or higher

4. Clear all caches:
   Terminal

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

Database Connection Error

Error: SQLSTATE[HY000] [2002] Connection refused or similar

Solutions:

• Verify database credentials in .env file are correct
• Ensure the database exists and user has proper permissions
• Check if MySQL/MariaDB service is running
• Try using DB_HOST=127.0.0.1 instead of localhost
• For remote databases, ensure firewall allows connections

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=cointrail
DB_USERNAME=your_username
DB_PASSWORD=your_password

Composer Dependencies Error

Error: Missing classes or autoload errors

# Reinstall dependencies
composer install --no-dev --optimize-autoloader

# Regenerate autoload files
composer dump-autoload

# Generate application key if missing
php artisan key:generate

# Cache configuration
php artisan config:cache

Runtime Issues

Prices Not Updating

If cryptocurrency prices are not updating automatically:

1. Verify cron job is configured:
   Crontab

   * * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

2. Check cron status in admin panel:

   Go to Admin → Settings → Cron Settings to see last run times

3. Review price update logs:

   Check storage/logs/laravel.log for API errors

4. Verify API quota:

   CoinGecko free tier allows 10,000 calls/month. Check if quota exceeded.

5. Test manually:
   Terminal

   php artisan crypto:update-prices --tier=top --limit=10

Email Not Sending

If emails (verification, alerts, notifications) are not being sent:

• Verify SMTP credentials in .env file
• For Gmail, use an App Password (not your regular password)
• Check if firewall allows outbound connections on port 587/465
• Review storage/logs/laravel.log for mail errors

Test email configuration:

php artisan tinker

# Then run:
Mail::raw('Test email', function($message) {
    $message->to('your@email.com')->subject('Test');
});

Payment Gateway Errors

Common payment issues and solutions:

• Webhook not working: Ensure webhook URLs are accessible (use HTTPS)
• Test vs Live mode: Verify you're using the correct API keys
• Currency mismatch: Ensure gateway supports your configured currency
• SSL required: Payment gateways require HTTPS

Performance Issues

Slow Page Load

Optimize performance with these commands:

# Cache configuration
php artisan config:cache
php artisan route:cache
php artisan view:cache

# Optimize composer autoloader
composer install --optimize-autoloader --no-dev

# Enable OPcache in php.ini
opcache.enable=1
opcache.memory_consumption=128

High Memory Usage

• Increase PHP memory_limit in php.ini: memory_limit = 256M
• Enable queue workers for heavy background tasks
• Use Redis for caching and sessions (recommended for high traffic)
• Enable database query caching

Common Error Messages

Enabling Debug Mode

To enable debug mode temporarily:

APP_DEBUG=true
APP_LOG_LEVEL=debug

After debugging, remember to disable:

APP_DEBUG=false
APP_LOG_LEVEL=error

Then clear the config cache:

php artisan config:cache

Log Files

CoinTrail stores logs in the storage/logs/ directory:

To view recent log entries:

# View last 100 lines
tail -n 100 storage/logs/laravel.log

# Watch log in real-time
tail -f storage/logs/laravel.log