shell-leaderboard/DEBUGGING.md

Debugging Strategy

CRITICAL: This template includes enhanced error tracking. Always check logs FIRST before guessing at solutions.

🚨 Golden Rule: Logs First, Guessing Never

When encountering errors:

❌ WRONG Approach:

1. See error message
2. Guess at the cause
3. Try random fixes
4. Waste time

✅ CORRECT Approach:

1. Check Laravel logs immediately
2. Read the full stack trace
3. Identify the exact file and line
4. Fix the root cause

---

Error Tracking Suite

This template includes:

• Spatie Laravel Ignition v2.11.0 - Enhanced error pages
• Spatie Flare Client v1.10.1 - Error tracking
• Laravel Logs - Full context and stack traces

---

How to Debug Errors

1. Check Laravel Logs (PRIMARY METHOD)

# View recent errors
docker-compose exec app tail -n 100 storage/logs/laravel.log

# Search for specific error
docker-compose exec app cat storage/logs/laravel.log | grep "ErrorType"

# Watch logs in real-time
docker-compose exec app tail -f storage/logs/laravel.log

What you'll see:

• Exact file path and line number
• Full stack trace
• Variable values at time of error
• User context (if logged in)

2. Check Container Logs

# Application logs
docker-compose logs --tail=50 app

# Nginx logs (for 502/504 errors)
docker-compose logs --tail=50 nginx

# All services
docker-compose logs --tail=50

3. Use Ignition Error Pages (Development)

When APP_DEBUG=true, Laravel shows beautiful error pages with:

• Code context (lines around the error)
• Stack trace with clickable frames
• Solution suggestions for common errors
• Request data and environment info

Access: Errors automatically show in browser during development

---

Common Error Patterns

TypeError: htmlspecialchars() expects string, array given

Log Location: storage/logs/laravel.log

What to look for:

htmlspecialchars(): Argument #1 ($string) must be of type string, array given
at /var/www/html/path/to/file.blade.php:LINE

Root Cause: Blade template trying to echo an array with {{ }}

Fix: Use proper component or @json() directive

---

504 Gateway Timeout

Log Location:

• docker-compose logs nginx
• storage/logs/laravel.log

What to look for:

upstream timed out (110: Operation timed out)

Common Causes:

• Stale cache after package installation
• Infinite loop in code
• Database query timeout
• Permission cache issues

Fix:

docker-compose exec app php artisan cache:clear
docker-compose exec app php artisan config:clear
docker-compose exec app php artisan view:clear
docker-compose exec app php artisan permission:cache-reset
docker-compose restart app nginx

---

Database Connection Errors

Log Location: storage/logs/laravel.log

What to look for:

SQLSTATE[HY000] [2002] Connection refused

Fix:

# Check if database is running
docker-compose ps

# Check database logs
docker-compose logs mysql

# Restart database
docker-compose restart mysql

# Wait for database to be ready
docker-compose exec mysql mysqladmin ping -h localhost

---

Redis Connection Errors

Log Location: storage/logs/laravel.log

What to look for:

php_network_getaddresses: getaddrinfo for redis failed

Fix:

# Check Redis is running
docker-compose ps redis

# Restart Redis
docker-compose restart redis

# Clear config cache
docker-compose exec app php artisan config:clear

---

Debugging Workflow for AI Agents

When a user reports an error, follow this exact sequence:

Step 1: Get the Full Error

docker-compose exec app cat storage/logs/laravel.log | grep -A 20 "ErrorType"

Step 2: Identify Root Cause

• Read the stack trace
• Find the originating file and line
• Understand what the code is trying to do

Step 3: Verify the Fix

• Make the change
• Clear relevant caches
• Test the specific scenario that caused the error

Step 4: Document

• Explain what was wrong
• Show the fix
• Explain why it works

---

Cache Clearing Commands

Always clear caches after:

• Installing new packages
• Changing configuration
• Modifying service providers
• Updating permissions/roles

# Clear all caches
docker-compose exec app php artisan optimize:clear

# Or individually
docker-compose exec app php artisan cache:clear
docker-compose exec app php artisan config:clear
docker-compose exec app php artisan route:clear
docker-compose exec app php artisan view:clear
docker-compose exec app php artisan permission:cache-reset

# Regenerate autoloader
docker-compose exec app composer dump-autoload

---

Performance Debugging

Slow Page Loads

Check:

1. Laravel Debugbar (if installed)
2. Query count and time
3. OPcache status
4. Redis connection

Commands:

# Check OPcache status
docker-compose exec app php -i | grep opcache

# Monitor Redis
docker-compose exec redis redis-cli monitor

# Check query logs
# Enable in config/database.php: 'log_queries' => true

---

Production Error Tracking

For production, consider:

1. Flare (https://flareapp.io)

   • Add FLARE_KEY to .env
   • Automatic error reporting
   • Error grouping and notifications

2. Sentry (alternative)

   composer require sentry/sentry-laravel
   

3. Log Aggregation

   • Papertrail
   • Loggly
   • CloudWatch

---

Best Practices

✅ DO:

• Check logs before making changes
• Read the full stack trace
• Clear caches after changes
• Test the specific error scenario
• Document the fix

❌ DON'T:

• Guess at solutions without checking logs
• Make multiple changes at once
• Skip cache clearing
• Assume the error message tells the whole story
• Leave debugging code in production

---

Quick Reference

Error Type	First Check	Quick Fix
TypeError	Laravel logs	Check variable types
504 Timeout	Nginx logs	Clear caches, restart
Database	MySQL logs	Check connection, restart DB
Redis	Laravel logs	Restart Redis, clear config
Permission	Laravel logs	permission:cache-reset
View	Laravel logs	view:clear
Route	Laravel logs	route:clear

---

Log File Locations

Service	Log Location
Laravel	storage/logs/laravel.log
Nginx	Docker logs: docker-compose logs nginx
PHP-FPM	Docker logs: docker-compose logs app
MySQL	Docker logs: docker-compose logs mysql
Redis	Docker logs: docker-compose logs redis

---

Emergency Commands

When everything is broken:

# Nuclear option - reset everything
docker-compose down
docker-compose up -d
docker-compose exec app php artisan optimize:clear
docker-compose exec app composer dump-autoload
docker-compose exec app php artisan migrate:fresh --seed

⚠️ WARNING: migrate:fresh will delete all data!

---

Remember: Logs are your friend. Always check them first. 🔍