Troubleshooting

🆘 Troubleshooting

Common Issues and Solutions

Issue 1: "ERR_CONNECTION_RESET" During Installation

Symptoms: Browser shows connection reset error when submitting database details or finalizing installation.

Cause: Laravel dev server restarts when .env file is modified.

Solution: ✅ Already fixed in the latest version! The installer now handles this automatically.

If you still experience this:

1. Clear browser cache
2. Restart the dev server: php artisan serve
3. Try installation again

Issue 2: Database Tables Are Empty

Symptoms: After installation, database tables exist but have no data.

Cause: Database seeders timed out or were skipped during installation.

Solution:

Run seeders manually:

php artisan db:seed --class=Database\Seeders\InstallationSeeder --force

Verify seeding worked:

php artisan tinker

Then run:

\Spatie\Permission\Models\Role::count()  // Should return 7
\App\Models\Setting::count()              // Should return 126+
\App\Models\Page::count()                 // Should return 4

Issue 3: 404 Error on Completion Page

Symptoms: After clicking "Finalize Installation", you get a 404 error.

Cause: Routes not loaded after installation lock file is created.

Solution: ✅ Already fixed in the latest version!

If you still experience this:

php artisan route:clear
php artisan config:clear
php artisan cache:clear

Issue 4: "Class Not Found" Errors

Symptoms: Errors about missing classes during installation.

Solution:

composer dump-autoload
php artisan clear-compiled
php artisan cache:clear

Issue 5: Permission Denied Errors

Symptoms: Errors about unable to write to storage or cache directories.

Solution:

# Linux/Mac
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

# Or use your hosting control panel

Issue 6: Database Connection Failed

Symptoms: "Could not connect to database" error.

Checklist:

• ✅ Database exists and is created
• ✅ Database credentials are correct
• ✅ Database user has full permissions
• ✅ Database host is correct (localhost or 127.0.0.1)
• ✅ Database port is correct (default: 3306)
• ✅ MySQL/MariaDB service is running

Test connection manually:

mysql -h localhost -u your_username -p your_database

Issue 7: Migrations Timeout

Symptoms: Migrations take too long and timeout.

Solution:

Run migrations manually:

php artisan migrate --force

For large databases:

# Increase PHP timeout
php -d max_execution_time=300 artisan migrate --force

Getting Help

If you're still experiencing issues:

1. Check Logs:

   tail -f storage/logs/laravel-*.log
   

2. Run Diagnostic Tool:

   php test-scripts/diagnose-seeder-issue.php
   

3. Check Installation Status: Visit: https://your-domain.com/install/status

4. Review Documentation:

   • READ_ME_FIRST.md - Quick start guide
   • INSTALLER_FINAL_SUMMARY.md - Complete documentation
   • dev-docs/ - Technical documentation