# 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)

```bash
# 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

```bash
# 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**:
```bash
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**:
```bash
# 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**:
```bash
# 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
```bash
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

```bash
# 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**:
```bash
# 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)
   ```bash
   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:

```bash
# 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. 🔍