================================================================================
                          Troubleshooting Guide
================================================================================

This guide helps you diagnose and fix common issues with your Laravel
application on CloudPanel. Issues are organized by category with
step-by-step solutions.

================================================================================
                          General Diagnostic Steps
================================================================================

When encountering any issue:

1. Check Error Logs:
   tail -f storage/logs/laravel.log
   tail -f /var/log/nginx/error.log
   
2. Enable Debug Mode (temporarily):
   APP_DEBUG=true in .env
   Warning: Disable after troubleshooting!
   
3. Clear All Caches:
   php artisan optimize:clear
   
4. Check Server Status:
   sudo systemctl status nginx
   sudo systemctl status php8.3-fpm
   sudo systemctl status mysql
   
5. Verify File Permissions:
   ls -la storage/
   ls -la bootstrap/cache/

================================================================================
                          Installation Issues
================================================================================

Problem: Installer Not Accessible
Symptoms: 404 error when visiting /install

Solutions:
1. Verify Document Root points to /public
   - CloudPanel > Sites > Settings > Document Root
   - Should be: /path/to/site/public

2. Check NGINX configuration
   - Must include: try_files $uri $uri/ /index.php?$query_string;

3. Clear route cache:
   php artisan route:clear

4. Verify installer is not disabled:
   - In .env: DISABLE_INSTALLER should be false
   - Or installer files exist in app/Http/Controllers/Installer/

--------------------------------------------------------------------------------

Problem: Requirements Check Fails
Symptoms: Red X marks on requirements page

Solutions:
1. PHP Version Too Low:
   - CloudPanel > PHP-FPM > Select PHP 8.2+
   
2. Missing PHP Extensions:
   - CloudPanel > PHP-FPM > Enable required extensions
   - Or via SSH: sudo apt-get install php8.3-[extension]
   
3. Directory Not Writable:
   chmod -R 775 storage bootstrap/cache
   chown -R www-data:www-data storage bootstrap/cache

4. Permission Denied:
   - Check SELinux: sudo setenforce 0 (temporarily)
   - Or set proper context: chcon -R -t httpd_sys_rw_content_t storage/

--------------------------------------------------------------------------------

Problem: Environment Configuration Fails
Symptoms: Error saving .env file

Solutions:
1. .env Not Writable:
   chmod 644 .env
   chown www-data:www-data .env

2. Disk Space Full:
   df -h
   # Clean up if needed

3. Database Connection Test Fails:
   - Verify credentials are correct
   - Test manually: mysql -u username -p -h hostname database
   - Check MySQL is running: sudo systemctl status mysql

--------------------------------------------------------------------------------

Problem: Dependencies Installation Hangs
Symptoms: Composer install never completes

Solutions:
1. Increase PHP Timeout:
   # In PHP-FPM settings
   max_execution_time = 300
   
2. Memory Limit Too Low:
   memory_limit = 512M

3. Composer Not Found:
   # Install composer
   php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
   php composer-setup.php
   php -r "unlink('composer-setup.php');"
   sudo mv composer.phar /usr/local/bin/composer

4. Network Issues:
   # Test connectivity
   ping packagist.org
   
   # Use different Composer repo if needed
   composer config repo.packagist composer https://packagist.org

================================================================================
                          Application Errors
================================================================================

Problem: 500 Internal Server Error
Symptoms: White page, "500 Internal Server Error"

Solutions:
1. Check Laravel Log:
   tail -f storage/logs/laravel.log
   
2. Common Causes:
   
   a) No APP_KEY:
      php artisan key:generate
      
   b) Wrong Permissions:
      chmod -R 775 storage bootstrap/cache
      chown -R www-data:www-data storage bootstrap/cache
      
   c) Missing .env:
      cp .env.example .env
      php artisan key:generate
      
   d) Syntax Error:
      php artisan config:clear
      # Check error message
      
   e) Outdated Cache:
      php artisan optimize:clear

3. Check NGINX Error Log:
   tail -f /var/log/nginx/error.log

4. Check PHP-FPM Log:
   tail -f /var/log/php8.3-fpm.log

--------------------------------------------------------------------------------

Problem: 404 Not Found
Symptoms: All routes return 404 except homepage

Solutions:
1. NGINX Rewrite Missing:
   # In NGINX config, ensure:
   location / {
       try_files $uri $uri/ /index.php?$query_string;
   }
   
2. .htaccess Not Used (NGINX):
   # Convert Apache .htaccess to NGINX config
   # Use deployment/nginx/laravel.conf

3. Route Cache Issue:
   php artisan route:clear
   php artisan route:cache

4. Wrong Document Root:
   # Must point to /public
   # CloudPanel > Settings > Document Root

--------------------------------------------------------------------------------

Problem: CSRF Token Mismatch
Symptoms: "419 Page Expired" on form submission

Solutions:
1. Session Not Working:
   # Check session driver in .env
   SESSION_DRIVER=database
   
   # If using database, create session table:
   php artisan session:table
   php artisan migrate

2. Domain Mismatch:
   # In .env, ensure:
   APP_URL=https://yourdomain.com
   SESSION_DOMAIN=null

3. Cache Issue:
   php artisan config:clear
   
4. Cookie Not Saved:
   # Check browser blocks cookies
   # Verify HTTPS if SESSION_SECURE_COOKIE=true

5. AJAX Missing Token:
   # In JavaScript:
   $.ajaxSetup({
       headers: {
           'X-CSRF-TOKEN': $('meta[name="csrf-token"]').attr('content')
       }
   });

--------------------------------------------------------------------------------

Problem: Class Not Found
Symptoms: "Class [ClassName] not found"

Solutions:
1. Autoload Not Updated:
   composer dump-autoload

2. Wrong Namespace:
   # Verify namespace matches directory structure
   # PSR-4: App\Models\User should be in app/Models/User.php

3. File Name Case Sensitive:
   # Linux is case-sensitive
   # User.php, not user.php

4. Clear Config Cache:
   php artisan config:clear

5. Reinstall Dependencies:
   rm -rf vendor/
   composer install

================================================================================
                          Database Issues
================================================================================

Problem: Database Connection Refused
Symptoms: "SQLSTATE[HY000] [2002] Connection refused"

Solutions:
1. MySQL Not Running:
   sudo systemctl start mysql
   sudo systemctl enable mysql

2. Wrong Host:
   # In .env, try:
   DB_HOST=127.0.0.1
   # or
   DB_HOST=localhost

3. Socket Connection:
   # If localhost doesn't work:
   DB_HOST=/var/run/mysqld/mysqld.sock

4. Firewall Blocking:
   sudo ufw allow 3306

5. MySQL Listening:
   netstat -an | grep 3306
   # Should show LISTEN

--------------------------------------------------------------------------------

Problem: Access Denied for User
Symptoms: "SQLSTATE[HY000] [1045] Access denied"

Solutions:
1. Wrong Credentials:
   # Verify in .env:
   DB_USERNAME=correct_username
   DB_PASSWORD=correct_password

2. User Not Exists:
   mysql -u root -p
   SELECT user, host FROM mysql.user;
   
3. Create User:
   CREATE USER 'username'@'localhost' IDENTIFIED BY 'password';
   GRANT ALL PRIVILEGES ON database.* TO 'username'@'localhost';
   FLUSH PRIVILEGES;

4. Host Mismatch:
   # User created for 'localhost' but connecting via '127.0.0.1'
   CREATE USER 'username'@'127.0.0.1' IDENTIFIED BY 'password';

--------------------------------------------------------------------------------

Problem: Unknown Database
Symptoms: "SQLSTATE[HY000] [1049] Unknown database"

Solutions:
1. Database Not Created:
   mysql -u root -p
   CREATE DATABASE database_name;

2. Wrong Database Name:
   # Check exact name in .env:
   DB_DATABASE=exact_database_name
   # MySQL is case-sensitive on Linux

3. Permissions Issue:
   SHOW DATABASES;
   # Verify user can see database

--------------------------------------------------------------------------------

Problem: Migration Fails
Symptoms: Error running php artisan migrate

Solutions:
1. Duplicate Column:
   # Migration already run
   php artisan migrate:status
   # Rollback if needed
   php artisan migrate:rollback

2. Table Already Exists:
   # Drop and recreate
   php artisan migrate:fresh
   # WARNING: Deletes all data!

3. Syntax Error in Migration:
   # Check migration file
   # Fix syntax
   # Run: php artisan migrate

4. Foreign Key Constraint:
   # Ensure parent table exists first
   # Check migration order
   # Disable foreign keys temporarily:
   SET FOREIGN_KEY_CHECKS=0;

================================================================================
                          Performance Issues
================================================================================

Problem: Slow Page Load
Symptoms: Pages take 5+ seconds to load

Solutions:
1. Debug Bar Analysis:
   composer require barryvdh/laravel-debugbar --dev
   # Shows queries, memory, time

2. N+1 Query Problem:
   # Use eager loading
   # Bad:
   $users = User::all();
   foreach ($users as $user) {
       echo $user->posts->count();
   }
   
   # Good:
   $users = User::with('posts')->get();
   foreach ($users as $user) {
       echo $user->posts->count();
   }

3. Missing Index:
   # Add index to frequently queried columns
   Schema::table('users', function (Blueprint $table) {
       $table->index('email');
   });

4. Cache Queries:
   $users = Cache::remember('users', 3600, function () {
       return User::all();
   });

5. OpCache Not Enabled:
   # In php.ini:
   opcache.enable=1
   opcache.memory_consumption=256

6. Large Log Files:
   # Rotate logs
   find storage/logs -name "*.log" -mtime +7 -delete

--------------------------------------------------------------------------------

Problem: High Memory Usage
Symptoms: PHP crashes, out of memory errors

Solutions:
1. Increase PHP Memory:
   # In php.ini or PHP-FPM pool:
   memory_limit = 512M

2. Reduce Query Results:
   # Use pagination
   $users = User::paginate(20);
   
   # Or chunking for large datasets
   User::chunk(100, function ($users) {
       foreach ($users as $user) {
           // Process
       }
   });

3. Unset Variables:
   unset($largeArray);

4. Memory Leak:
   # Check for circular references
   # Profile with Xdebug

================================================================================
                          Queue & Job Issues
================================================================================

Problem: Jobs Not Processing
Symptoms: Queued jobs never execute

Solutions:
1. Queue Worker Not Running:
   ps aux | grep queue:work
   
   # Start worker:
   php artisan queue:work

2. Using Sync Driver:
   # In .env, change:
   QUEUE_CONNECTION=database
   # Not: sync

3. Failed Jobs:
   # Check failed_jobs table:
   SELECT * FROM failed_jobs;
   
   # Retry failed jobs:
   php artisan queue:retry all

4. Supervisor Not Running:
   sudo supervisorctl status
   sudo supervisorctl start laravel-worker:*

5. Job Timeout:
   # In job class:
   public $timeout = 300;  // 5 minutes

--------------------------------------------------------------------------------

Problem: Queue Worker Crashes
Symptoms: Supervisor constantly restarting worker

Solutions:
1. Check Worker Logs:
   tail -f storage/logs/worker.log

2. Memory Limit:
   # In supervisor config:
   command=php artisan queue:work --memory=512

3. Job Exception:
   # Check failed_jobs table
   # Fix code causing exception

4. Database Connection:
   # Refresh connection in long-running workers:
   DB::reconnect();

================================================================================
                          Email Issues
================================================================================

Problem: Emails Not Sending
Symptoms: No emails received

Solutions:
1. Check Mail Configuration:
   # In .env:
   MAIL_MAILER=smtp
   MAIL_HOST=smtp.mailtrap.io
   MAIL_PORT=2525
   MAIL_USERNAME=your_username
   MAIL_PASSWORD=your_password

2. Test Email:
   php artisan tinker
   Mail::raw('Test email', function ($message) {
       $message->to('test@example.com')->subject('Test');
   });

3. Check Logs:
   tail -f storage/logs/laravel.log
   # Look for mail errors

4. Firewall Blocking SMTP:
   telnet smtp.host.com 587
   # Should connect

5. Using Queue:
   # If email is queued, ensure worker running
   php artisan queue:work

6. Gmail Specific:
   - Enable "Less secure apps" or use App Password
   - Check "Allow less secure apps" in Gmail settings

--------------------------------------------------------------------------------

Problem: Emails in Spam
Symptoms: Emails delivered but in spam folder

Solutions:
1. SPF Record:
   # Add to DNS:
   v=spf1 include:_spf.yourdomain.com ~all

2. DKIM:
   # Configure DKIM in your mail provider
   # Add DKIM record to DNS

3. DMARC:
   # Add to DNS:
   _dmarc.yourdomain.com TXT "v=DMARC1; p=quarantine; rua=mailto:postmaster@yourdomain.com"

4. From Address:
   # Use domain email, not gmail/yahoo
   MAIL_FROM_ADDRESS=noreply@yourdomain.com

5. Content Filters:
   # Avoid spam trigger words
   # Don't use ALL CAPS
   # Include unsubscribe link

================================================================================
                          File Upload Issues
================================================================================

Problem: Upload Fails with "File Too Large"
Symptoms: Error uploading large files

Solutions:
1. Increase Upload Limits:
   # In php.ini:
   upload_max_filesize = 50M
   post_max_size = 50M
   
   # In NGINX:
   client_max_body_size 50M;

2. Restart Services:
   sudo systemctl restart php8.3-fpm
   sudo systemctl restart nginx

3. Check Form:
   <form enctype="multipart/form-data">

4. Validation:
   $request->validate([
       'file' => 'required|max:51200', // 50MB in KB
   ]);

--------------------------------------------------------------------------------

Problem: Uploaded Files Not Found
Symptoms: 404 error on uploaded file URL

Solutions:
1. Storage Link Missing:
   php artisan storage:link
   
   # Verify symlink exists:
   ls -la public/storage

2. Wrong Path:
   # Store in public disk:
   $path = $request->file('avatar')->store('avatars', 'public');
   
   # URL:
   asset('storage/' . $path)

3. Permissions:
   chmod -R 775 storage/app/public
   chown -R www-data:www-data storage/app/public

================================================================================
                          Session & Authentication
================================================================================

Problem: Users Logged Out Randomly
Symptoms: Session expires unexpectedly

Solutions:
1. Session Lifetime Too Short:
   # In .env:
   SESSION_LIFETIME=120  # minutes

2. Session Driver Issues:
   # Switch to database:
   SESSION_DRIVER=database
   php artisan session:table
   php artisan migrate

3. Cookie Domain:
   # In .env:
   SESSION_DOMAIN=.yourdomain.com  # For subdomains
   # Or:
   SESSION_DOMAIN=null  # For single domain

4. Cache Cleared:
   # Don't clear session storage:
   # Be careful with: php artisan cache:clear

5. Load Balancer:
   # Use database/redis for sessions
   # Not file driver

--------------------------------------------------------------------------------

Problem: Login Fails Silently
Symptoms: Credentials correct but not logged in

Solutions:
1. Check User Provider:
   # In config/auth.php:
   'providers' => [
       'users' => [
           'driver' => 'eloquent',
           'model' => App\Models\User::class,
       ],
   ],

2. Password Hash:
   # Ensure password hashed:
   Hash::make($password)

3. Remember Me:
   # Ensure remember_token column exists in users table

4. Session Working:
   # Test session:
   session(['test' => 'value']);
   dd(session('test'));

================================================================================
                          CloudPanel Specific Issues
================================================================================

Problem: Changes Not Reflecting
Symptoms: Code changes don't appear on site

Solutions:
1. OpCache Not Cleared:
   # In CloudPanel > PHP-FPM > OPcache
   # Click "Clear OPcache"
   
   # Or via code:
   opcache_reset();

2. Browser Cache:
   # Hard refresh: Ctrl+F5
   # Or clear browser cache

3. Wrong Directory:
   # Ensure editing files in correct location
   # Check: CloudPanel > File Manager

4. NGINX Not Reloaded:
   sudo systemctl reload nginx

--------------------------------------------------------------------------------

Problem: Cron Jobs Not Running
Symptoms: Scheduled tasks don't execute

Solutions:
1. Cron Not Set:
   crontab -e
   # Add:
   * * * * * php /path/to/artisan schedule:run >> /dev/null 2>&1

2. Wrong Path:
   # Use absolute path
   which php  # Get PHP path
   pwd  # Get artisan path

3. Permissions:
   chmod +x artisan

4. PHP CLI Version:
   # Ensure correct PHP version used in cron
   /usr/bin/php8.3 /path/to/artisan schedule:run

5. Environment Variables:
   # Cron may not have .env loaded
   # Use absolute paths in cron

================================================================================
                          Debugging Tools & Commands
================================================================================

Essential Commands:

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

# Laravel tinker (interactive shell)
php artisan tinker

# List all routes
php artisan route:list

# View configuration
php artisan config:show

# Check database connection
php artisan db:show

# Clear everything
php artisan optimize:clear

# View all artisan commands
php artisan list

# Get help on command
php artisan help migrate

Server Diagnostics:

# Check disk space
df -h

# Check memory
free -m

# Check CPU
top

# Check processes
ps aux | grep php
ps aux | grep nginx

# Check ports
netstat -tuln | grep :80
netstat -tuln | grep :3306

# Check PHP-FPM status
sudo systemctl status php8.3-fpm

# Check NGINX status
sudo systemctl status nginx

# View NGINX error log
tail -f /var/log/nginx/error.log

# View PHP-FPM error log
tail -f /var/log/php8.3-fpm.log

# Test NGINX config
sudo nginx -t

================================================================================
                          Getting Additional Help
================================================================================

If issue persists after trying solutions:

1. Gather Information:
   - Exact error message
   - Laravel version: php artisan --version
   - PHP version: php -v
   - Steps to reproduce
   - Relevant logs

2. Check Documentation:
   - Laravel: https://laravel.com/docs
   - CloudPanel: https://www.cloudpanel.io/docs

3. Community Support:
   - Laravel Forums: https://laracasts.com/discuss
   - Stack Overflow: Tag with [laravel]
   - Laravel Discord: https://discord.gg/laravel

4. Professional Support:
   - Laravel Forge support
   - CloudPanel support
   - Hire Laravel developer

5. Debug Mode Info:
   - Enable APP_DEBUG=true temporarily
   - Take screenshot of error
   - Disable before going public!

================================================================================

Remember: Most issues are permissions, configuration, or caching related.
Always check logs first!

For configuration reference, see CONFIGURATION.txt
For security best practices, see SECURITY.txt
For operational procedures, see OPERATIONS.txt