marwa-framework

Troubleshooting

This guide covers common issues and how to fix them.

General Issues

“Class Not Found” Error

Symptom:

Error: Class 'App\Controllers\UserController' not found

Solution:

composer dump-autoload

Blank White Page

Symptom: White screen with no error message.

Solutions:

  1. Enable error display in .env: 
    APP_DEBUG=true
  2. Check PHP error logs: 
    tail -f storage/logs/app.log
  3. Check PHP error log location: 
    php -i | grep error_log

500 Internal Server Error

Symptom: HTTP 500 error response.

Solutions:

  1. Check the error log: 
    tail -f storage/logs/app.log
  2. Enable debug mode: 
    APP_DEBUG=true
  3. Check permissions: 
    chmod -R 775 storage/
chmod -R 775 bootstrap/cache/

Database Issues

“Database Not Found”

Symptom:

SQLSTATE[HY000]: General error: 14 unable to open database file

Solution (SQLite):

touch database/app.sqlite
chmod 775 database/app.sqlite

“Access Denied for User”

Symptom:

SQLSTATE[28000]: Access denied for user 'root'@'localhost'

Solution: Check .env:

DB_HOST=localhost
DB_USERNAME=your_username
DB_PASSWORD=your_password

Migration Failed

Symptom: Migration errors.

Solutions:

  1. Check database connection in .env
  2. Run with verbose output: 
    php marwa migrate -vvv
  3. Check migrations path in config/database.php

“No Such Table”

Symptom: Table doesn’t exist errors.

Solution: Run migrations:

php marwa migrate

Session Issues

“Session Not Starting”

Symptom: Sessions don’t persist.

Solution:

  1. Check session config in config/session.php
  2. Ensure storage is writable: 
    chmod -R 775 storage/framework/sessions/

Symptom: Login doesn’t persist.

Solution: Check cookie settings:

// config/session.php
return [
    'driver' => 'cookie', // or 'file'
    'cookie_name' => 'marwa_session',
    'cookie_lifetime' => 120,
];

Email Issues

“SMTP Connection Failed”

Symptom: Email not sending.

Solution: Check mail config in config/mail.php:

return [
    'driver' => 'smtp',
    'host' => 'smtp.mailtrap.io',
    'port' => 2525,
    'username' => 'your_username',
    'password' => 'your_password',
];

“From Address Invalid”

Symptom: Email validation error.

Solution: Set valid from address:

return [
    'from' => [
        'address' => 'noreply@yourdomain.com',
        'name' => 'Your App',
    ],
];

Cache Issues

“Cache Not Working”

Symptom: Cached data doesn’t persist.

Solutions:

  1. Clear cache: 
    php marwa cache:clear
  2. Check cache driver in .env: 
    CACHE_DRIVER=file

“Route Cache Error”

Symptom: Routes not loading after caching.

Solution: Clear route cache:

php marwa route:clear

Console Issues

“Command Not Found”

Symptom:

Command "make:user" is not defined.

Solution:

php marwa list

to see available commands.

“Permission Denied”

Symptom: Cannot execute marwa.

Solution:

chmod +x marwa

Permission Issues

“Permission Denied” on Storage

Solution:

# Linux/Apache
sudo chown -R www-data:www-data storage/ bootstrap/cache/

# macOS
sudo chown -R _www:_www storage/ bootstrap/cache/

“Directory Not Writable”

Solution:

chmod -R 775 storage/
chmod -R 775 bootstrap/cache/
chmod -R 775 database/

Performance Issues

Slow Response Times

Solutions:

  1. Enable route caching: 
    php marwa route:cache
  2. Use OPcache: 
    ; php.ini
opcache.enable=1
opcache.memory_consumption=128
  3. Disable Xdebug in production: 
    ; php.ini
xdebug.mode=off

High Memory Usage

Solutions:

  1. Check for N+1 queries in models
  2. Use eager loading: 
    $users = User::with('posts')->get();
  3. Optimize database queries with indexes

Getting Help

Enable Debug Mode

APP_DEBUG=true
APP_ENV=local

Check Logs

# Application logs
tail -f storage/logs/app.log

# Framework logs
tail -f storage/logs/framework.log

Run Tests

composer test

Run Static Analysis

composer stan

Common Error Codes

Code Meaning Solution
404 Not found Check route exists
500 Server error Check logs
419 CSRF token Refresh page
422 Validation Check input
401 Unauthorized Check auth

Next Steps

This site is open source. Improve this page.