Lara Dashboard Lara Dashboard
/
main (default) 0.x

Troubleshooting Guide

Solutions to common problems and issues when running LaraDashboard, including installation errors, performance issues, and configuration problems.

Troubleshooting Guide

This guide provides solutions to common issues you may encounter when running LaraDashboard.

Installation Issues

Composer Install Fails

Symptom: Memory error during composer install

Solution:

# Increase memory limit
COMPOSER_MEMORY_LIMIT=-1 composer install

# Or use swap on low-memory servers
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Key Generation Error

Symptom: "No application encryption key has been specified"

Solution:

php artisan key:generate
php artisan config:clear

Database Connection Error

Symptom: "SQLSTATE[HY000] [2002] Connection refused"

Solutions:

  1. Check MySQL is running: systemctl status mysql
  2. Verify database credentials in .env
  3. Check socket path: DB_SOCKET=/var/run/mysqld/mysqld.sock
  4. For remote DB, ensure firewall allows connection

Migration Fails

Symptom: Migration error or timeout

Solutions:

# Clear failed migrations
php artisan migrate:reset

# Run with verbose output
php artisan migrate -v

# Check for syntax errors
php artisan migrate:status

Application Errors

500 Internal Server Error

Possible Causes & Solutions:

  1. Permissions Issue

    sudo chown -R www-data:www-data storage bootstrap/cache
sudo chmod -R 775 storage bootstrap/cache

  2. Missing .env

    cp .env.example .env
php artisan key:generate

  3. Cache Issue

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

  4. Check Logs

    tail -f storage/logs/laravel.log

404 Not Found

Possible Causes:

  1. Routing Issue

    php artisan route:clear
php artisan route:list

  2. Web Server Config

    • Ensure mod_rewrite enabled (Apache)
    • Check try_files directive (Nginx)

  3. Missing .htaccess

    • Verify .htaccess exists in public/

419 Page Expired

Symptom: CSRF token mismatch

Solutions:

  1. Check SESSION_DRIVER configuration
  2. Clear browser cookies
  3. Verify session directory is writable
  4. Check APP_URL matches actual domain

502 Bad Gateway

Solutions:

  1. Check PHP-FPM is running

    systemctl status php8.3-fpm
systemctl restart php8.3-fpm

  2. Verify socket path in Nginx config matches PHP-FPM

  3. Increase PHP-FPM timeout

    fastcgi_read_timeout 300;

Performance Issues

Slow Page Load

Diagnostic Steps:

  1. Enable Debug Bar (development only)

    composer require barryvdh/laravel-debugbar --dev

  2. Check Query Count

    • Look for N+1 queries
    • Add eager loading

  3. Enable Caching

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

  4. Use Redis

    CACHE_DRIVER=redis
SESSION_DRIVER=redis

High Memory Usage

Solutions:

  1. Optimize PHP-FPM

    pm = dynamic
pm.max_children = 20
pm.start_servers = 5
pm.min_spare_servers = 5
pm.max_spare_servers = 10

  2. Limit Eloquent Memory

    // Use chunking for large datasets
Post::chunk(1000, function ($posts) {
    // Process
});

  3. Clear Old Data

    • Prune telescope entries
    • Clean old logs
    • Remove unused sessions

Database Slow

Solutions:

  1. Add Indexes

    SHOW INDEX FROM posts;
ALTER TABLE posts ADD INDEX idx_status_published (status, published_at);

  2. Optimize Tables

    OPTIMIZE TABLE posts;

  3. Increase MySQL Memory

    innodb_buffer_pool_size = 1G

Authentication Issues

Cannot Login

Solutions:

  1. Reset Password via Tinker

    php artisan tinker
>>> $user = User::where('email', 'admin@example.com')->first();
>>> $user->password = bcrypt('newpassword');
>>> $user->save();

  2. Check Session Driver

    SESSION_DRIVER=file

  3. Clear Session Data

    php artisan session:clear

Session Expires Quickly

Solutions:

  1. Increase Lifetime

    SESSION_LIFETIME=120

  2. Check Cookie Domain

    SESSION_DOMAIN=yourdomain.com

Email Verification Not Working

Solutions:

  1. Check Mail Config

    php artisan tinker
>>> Mail::raw('Test', fn($m) => $m->to('test@test.com'));

  2. Verify Routes

    php artisan route:list | grep verif

File Upload Issues

Upload Fails

Solutions:

  1. Increase PHP Limits

    ; php.ini
upload_max_filesize = 100M
post_max_size = 100M
max_execution_time = 300

  2. Nginx Config

    client_max_body_size 100M;

  3. Check Permissions

    chmod -R 775 storage/app/public

Images Not Displaying

Solutions:

  1. Create Storage Link

    php artisan storage:link

  2. Check URL Configuration

    APP_URL=https://yourdomain.com

  3. Verify File Exists

    ls -la storage/app/public/

Email Issues

Emails Not Sending

Diagnostic Steps:

  1. Test Configuration

    php artisan tinker
>>> Mail::raw('Test email', fn($m) => $m->to('test@email.com')->subject('Test'));

  2. Check Logs

    tail -f storage/logs/laravel.log | grep -i mail

  3. Use Simpler Driver First

    MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your@gmail.com
MAIL_PASSWORD=app-password
MAIL_ENCRYPTION=tls

Emails Going to Spam

Solutions:

  1. Configure SPF record
  2. Set up DKIM signing
  3. Configure DMARC
  4. Use reputable email service

Queue Issues

Jobs Not Processing

Solutions:

  1. Check Worker is Running

    php artisan queue:work --verbose

  2. Restart Workers

    php artisan queue:restart
supervisorctl restart all

  3. Check Failed Jobs

    php artisan queue:failed
php artisan queue:retry all

Jobs Failing

Solutions:

  1. Check Job Logs

    php artisan queue:failed

  2. Increase Timeout

    php artisan queue:work --timeout=600

  3. Debug Job

    // In job class
public function failed(\Throwable $exception)
{
    Log::error('Job failed: ' . $exception->getMessage());
}

Module Issues

Module Not Loading

Solutions:

  1. Clear Cache

    php artisan module:clear-compiled
php artisan cache:clear

  2. Check module.json Syntax

    cat modules/YourModule/module.json | jq .

  3. Verify Namespace

    composer dump-autoload

Module Migration Error

Solutions:

# Check status
php artisan module:migrate-status ModuleName

# Reset and retry
php artisan module:migrate-rollback ModuleName
php artisan module:migrate ModuleName

Asset Issues

CSS/JS Not Loading

Solutions:

  1. Build Assets

    npm run build

  2. Check Vite Manifest

    cat public/build/manifest.json

  3. Clear Browser Cache

    • Hard refresh: Ctrl+Shift+R

  4. Check APP_URL

    APP_URL=https://yourdomain.com

Vite Dev Server Issues

Solutions:

# Kill existing processes
killall node

# Clear npm cache
npm cache clean --force

# Reinstall
rm -rf node_modules package-lock.json
npm install
npm run dev

Debug Mode

Enable Debugging (Development Only)

APP_DEBUG=true
APP_ENV=local

Laravel Telescope

# Install (dev only)
composer require laravel/telescope --dev
php artisan telescope:install
php artisan migrate

Access at: /telescope

Log Channels

LOG_CHANNEL=stack
LOG_LEVEL=debug

View logs:

tail -f storage/logs/laravel.log

Getting Help

Collect Debug Information

Before seeking help, gather:

  1. Laravel Version

    php artisan --version

  2. PHP Version

    php -v

  3. Error Logs

    tail -100 storage/logs/laravel.log

  4. Environment Info

    php artisan about

Support Channels

  • Documentation - Check relevant docs first
  • GitHub Issues - Report bugs with reproduction steps
  • Stack Overflow - Tag with laradashboard and laravel

Next Steps

Edit this page on GitHub
/