Troubleshooting Guide

Common issues and their solutions.

Installation Issues

Docker containers won't start

Symptoms:

• docker compose up fails
• Containers exit immediately

Solutions:

1. Check Docker is running:

   docker info
   

2. Check for port conflicts:

   # Linux/macOS
   netstat -tulpn | grep -E '80|443|5432|6379'
   
   # Windows
   netstat -ano | findstr "80 443 5432 6379"
   

3. Free ports or change in docker-compose.yml:

   ports:
     - "8080:80"  # Use 8080 instead of 80
   

4. View container logs:

   docker compose logs -f app
   docker compose logs -f db
   

"Class not found" errors

Symptoms:

• Class 'App\...' not found
• Target class does not exist

Solutions:

# Regenerate autoloader
composer dump-autoload

# Clear all caches
php artisan config:clear
php artisan cache:clear
php artisan view:clear
php artisan route:clear

# Docker:
docker compose exec app composer dump-autoload
docker compose exec app php artisan optimize:clear

Database connection refused

Symptoms:

• SQLSTATE[08006] Connection refused
• could not connect to server

Solutions:

1. Docker users: Use db as host, not localhost:

   DB_HOST=db
   

2. Check database is running:

   docker compose ps
   # Should show db as "healthy"
   

3. Verify credentials match .env:

   docker compose exec db psql -U tenanto -d tenanto -c "SELECT 1"
   

4. Wait for database startup (can take 30+ seconds on first run)

Migration errors

Symptoms:

• Migration table not found
• Relation does not exist

Solutions:

# Fresh migration (WARNING: deletes all data)
php artisan migrate:fresh --seed

# Or reset and re-run
php artisan migrate:reset
php artisan migrate --seed

Authentication Issues

Can't log in to admin panel

Symptoms:

• Login form shows but credentials don't work
• "Invalid credentials" error

Solutions:

1. Verify admin user exists:

   docker compose exec app php artisan tinker
   >>> \App\Models\User::where('email', '[email protected]')->first()
   

2. Reset password:

   docker compose exec app php artisan tinker
   >>> $user = \App\Models\User::where('email', '[email protected]')->first();
   >>> $user->password = bcrypt('newpassword');
   >>> $user->save();
   

3. Re-run seeders:

   docker compose exec app php artisan db:seed --class=AdminSeeder
   

Can't access tenant panel

Symptoms:

• Redirected to login repeatedly
• 403 Forbidden error

Solutions:

1. Verify tenant exists and is active:

   docker compose exec app php artisan tinker
   >>> \App\Models\Tenant::where('slug', 'demo')->first()
   

2. Check user belongs to tenant:

   >>> \App\Models\User::where('email', '[email protected]')->with('tenant')->first()
   

3. Verify subdomain is configured in hosts file

Session issues

Symptoms:

• Logged out unexpectedly
• Can't maintain login state

Solutions:

1. Check session driver:

   SESSION_DRIVER=redis
   

2. Verify Redis is running:

   docker compose exec redis redis-cli ping
   # Should return: PONG
   

3. Clear sessions:

   php artisan session:table
   php artisan migrate
   # Or for Redis:
   docker compose exec redis redis-cli FLUSHDB
   

Billing Issues

Stripe webhook errors

Symptoms:

• Subscriptions not updating
• "Webhook signature verification failed"

Solutions:

1. Verify webhook secret:

   STRIPE_WEBHOOK_SECRET=whsec_xxxxx
   

   Must match the signing secret in Stripe Dashboard.

2. Check webhook URL is accessible:

   curl -X POST https://yourdomain.com/stripe/webhook
   # Should return error (no signature) but not 404
   

3. Use Stripe CLI for local testing:

   stripe listen --forward-to localhost/stripe/webhook
   

4. Check Laravel logs:

   tail -f storage/logs/laravel.log
   

"No such price" error

Symptoms:

• Checkout fails
• "No such price: price_xxx"

Solutions:

1. Verify price exists in Stripe Dashboard

2. Check correct mode (test vs live):

   # Test mode
   STRIPE_KEY=pk_test_xxx
   STRIPE_SECRET=sk_test_xxx
   
   # Live mode
   STRIPE_KEY=pk_live_xxx
   STRIPE_SECRET=sk_live_xxx
   

3. Verify price ID in .env:

   STRIPE_PRICE_BASIC=price_xxx
   

Performance Issues

Slow page loads

Solutions:

1. Enable caching:

   CACHE_DRIVER=redis
   

2. Optimize autoloader:

   composer install --optimize-autoloader --no-dev
   

3. Cache config/routes:

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

4. Check for N+1 queries (enable query logging):

   // In AppServiceProvider::boot()
   \DB::listen(function ($query) {
       \Log::info($query->sql);
   });
   

High memory usage

Solutions:

1. Increase PHP memory limit:

   ; php.ini
   memory_limit = 256M
   

2. For Docker, edit docker/php/php.ini

3. Process large datasets in chunks:

   Model::chunk(100, function ($items) {
       // Process
   });
   

Queue Issues

Jobs not processing

Symptoms:

• Emails not sending
• Background tasks stuck

Solutions:

1. Check queue worker is running:

   docker compose ps queue
   # Should show "Up"
   

2. Restart queue worker:

   docker compose restart queue
   

3. Check failed jobs:

   php artisan queue:failed
   

4. Retry failed jobs:

   php artisan queue:retry all
   

5. Process jobs manually:

   php artisan queue:work --once
   

Email Issues

Emails not sending

Solutions:

1. For development, use Mailhog:

   MAIL_MAILER=smtp
   MAIL_HOST=mailhog
   MAIL_PORT=1025
   

   View at http://localhost:8025

2. For production, configure SMTP:

   MAIL_MAILER=smtp
   MAIL_HOST=smtp.mailgun.org
   MAIL_PORT=587
   MAIL_USERNAME=your-username
   MAIL_PASSWORD=your-password
   MAIL_ENCRYPTION=tls
   

3. Test email sending:

   php artisan tinker
   >>> \Mail::raw('Test', fn($m) => $m->to('[email protected]'))
   

API Issues

Rate limit exceeded

Symptoms:

• 429 Too Many Requests
• X-RateLimit-Remaining: 0

Solutions:

1. Wait for rate limit reset (check Retry-After header)

2. Reduce request frequency

3. For testing, increase limits in app/Providers/RouteServiceProvider.php:

   RateLimiter::for('api', function (Request $request) {
       return Limit::perMinute(1000); // Increase for testing
   });
   

Authentication failures

Symptoms:

• 401 Unauthorized
• "Unauthenticated"

Solutions:

1. Verify token is valid:

   curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://domain.com/api/v1/auth/me
   

2. Check token hasn't expired (default 7 days)

3. Generate new token via login endpoint

General Debugging

Enable debug mode

For development only:

APP_DEBUG=true

Check logs

# Laravel logs
tail -f storage/logs/laravel.log

# Docker logs
docker compose logs -f app
docker compose logs -f nginx

Clear all caches

php artisan optimize:clear
# or
php artisan config:clear
php artisan cache:clear
php artisan route:clear
php artisan view:clear
composer dump-autoload

Verify environment

php artisan about

Getting More Help

If you can't resolve the issue:

1. Check documentation
2. Review FAQ
3. Contact [email protected] with:
   • Issue description
   • Steps to reproduce
   • Error logs
   • Environment details