Ashie AI Resume | JobPortal - Troubleshooting Guide

🔧 Installation Issues

Common problems encountered during or after installation.

Blank White Page After Installation

Possible Causes:

PHP errors are being suppressed
Missing PHP extensions
File permissions issues

Solution

Enable error display in .env file:
```
APP_DEBUG=true
```
Check PHP error logs (usually in /var/log/php/ or hosting panel)

Verify required PHP extensions are installed:

php -m | grep -E "pdo|mbstring|openssl|tokenizer|xml|curl|json"

Fix file permissions:

chmod -R 755 /path/to/backend
chmod -R 775 /path/to/backend/storage
chmod -R 775 /path/to/backend/bootstrap/cache

500 Internal Server Error

Possible Causes:

.htaccess conflicts
Missing APP_KEY
Database connection failure

Solution

Check if APP_KEY is set in .env. If not, generate one:
```
php artisan key:generate
```

Verify database credentials in .env:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database_name
DB_USERNAME=your_username
DB_PASSWORD=your_password

Clear configuration cache:

php artisan config:clear
php artisan cache:clear

CSS/JS Files Not Loading (404 Errors)

Possible Causes:

Document root not pointing to public folder
Missing symlink for storage

Solution

Ensure your domain's document root is set to /public folder
Create storage symlink:
```
php artisan storage:link
```
Verify APP_URL in .env matches your actual domain:
```
APP_URL=https://yourdomain.com
```

🔐 Login Problems

Issues with authentication and user access.

Can't Login - "Invalid Credentials"

Possible Causes:

Wrong email or password
Account doesn't exist in database
Session/cache issues

Solution

Use the demo credentials if testing:

Email: superadmin@test.com
Password: password123

Check if user exists in database

Clear application cache:

php artisan cache:clear
php artisan config:clear

If needed, reset password via database:

php artisan tinker
>>> User::where('email', 'superadmin@test.com')->update(['password' => bcrypt('newpassword')]);

Session Expires Too Quickly

Possible Causes:

Session configuration issues
Different domains for API and frontend

Solution

Check session settings in .env:

SESSION_LIFETIME=120
SESSION_DRIVER=file

Ensure cookies domain is set correctly:
```
SESSION_DOMAIN=.yourdomain.com
```

Admin Panel Access Denied

Possible Causes:

User doesn't have admin role
Role permissions not seeded

Solution

Check user's role in database (roles and model_has_roles tables)

Re-run seeders if needed:

php artisan db:seed --class=RoleSeeder

Assign admin role manually:

php artisan tinker
>>> $user = User::where('email', 'your@email.com')->first();
>>> $user->assignRole('super_admin');

📧 Email Issues

Problems with sending emails and notifications.

Emails Not Being Sent

Possible Causes:

SMTP credentials incorrect
Server blocking outbound SMTP
Queue worker not running

Solution

Verify SMTP settings in .env:

MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-app-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@yourdomain.com
MAIL_FROM_NAME="${APP_NAME}"

For Gmail, use an App Password, not your regular password

Test email configuration:

php artisan tinker
>>> Mail::raw('Test email', function($msg) { $msg->to('your@email.com')->subject('Test'); });

If using queue, ensure worker is running:
```
php artisan queue:work
```

Emails Going to Spam

Possible Causes:

Missing SPF/DKIM/DMARC records
Sending from different domain than configured
New domain with no reputation

Solution

Set up proper DNS records for your email domain (SPF, DKIM, DMARC)
Use a reputable email service like Mailgun, SendGrid, or Amazon SES
Ensure MAIL_FROM_ADDRESS matches your authenticated domain
Start with low sending volume to build reputation

💳 Payment Problems

Issues with payment processing and subscriptions.

Payments Not Processing

Possible Causes:

Payment gateway not enabled
Using sandbox credentials in live mode (or vice versa)
API keys incorrect

Solution

Go to Admin Panel → Settings → Payment Gateway
Verify the gateway is enabled (toggle is green)
Ensure you're using the correct credentials for your mode:
- Sandbox Mode: Use test/sandbox API keys
- Live Mode: Use production API keys
Test with gateway's test card numbers first

Webhook Not Receiving Events

Possible Causes:

Webhook URL not configured in payment gateway dashboard
Webhook secret incorrect
SSL certificate issues

Solution

Set up webhook URL in your payment gateway dashboard:

Stripe: https://yourdomain.com/api/v1/webhooks/stripe
PayPal: https://yourdomain.com/api/v1/webhooks/paypal
Flutterwave: https://yourdomain.com/api/v1/webhooks/flutterwave

Copy the webhook secret from gateway dashboard and add to admin settings
Ensure your site has a valid SSL certificate
Check webhook logs in the payment gateway dashboard

Subscription Not Activated After Payment

Possible Causes:

Webhook failed to process
Queue worker not running
Database error

Solution

Check if webhook was received (look in failed_jobs table)
Ensure queue worker is running:
```
php artisan queue:work
```
Manually activate subscription via Admin Panel → Subscriptions
Check Laravel logs for errors:
```
tail -f storage/logs/laravel.log
```

⚡ Performance Issues

Slow loading times and optimization tips.

Website Loading Slowly

Possible Causes:

Configuration not cached
Database queries not optimized
No CDN configured

Solution

Enable production optimizations:

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

Enable OPcache in PHP configuration

Set up Redis for caching (if available):

CACHE_DRIVER=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

Consider using a CDN (Cloudflare, CloudFront, etc.)

High Server Memory Usage

Possible Causes:

Queue workers consuming memory
Too many background processes

Solution

Restart queue workers periodically:
```
php artisan queue:restart
```
Use Supervisor to manage queue workers with memory limits
Consider upgrading server resources if consistently high

🚫 Common Error Messages

Understanding and resolving specific error messages.

"CSRF Token Mismatch"

Solution

Clear browser cookies and cache
Ensure your domain/subdomain settings are consistent
Check SESSION_DOMAIN in .env
Clear application cache:
```
php artisan cache:clear
```

"The page has expired due to inactivity"

Solution

Increase session lifetime in .env:
```
SESSION_LIFETIME=120
```
Clear browser cache and try again

Ensure session folder is writable:

chmod 775 storage/framework/sessions

"Failed to open stream: Permission denied"

Solution

Fix storage permissions:

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

Clear all caches:

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

"Class not found" Errors

Solution

Regenerate autoload files:
```
composer dump-autoload
```

Clear all caches:

php artisan clear-compiled
php artisan optimize:clear

🆘 Getting Help

When you can't solve an issue on your own.

Before Contacting Support

Please gather the following information:

Detailed description of the problem
Steps to reproduce the issue
Error messages (screenshot or copy text)
Your PHP version (php -v)
Contents of .env (with sensitive data removed)
Recent entries from storage/logs/laravel.log

Contact Support

📧 Email: support@dafriappsdev.com

🌐 Support Portal: dafriappsdev.com/user-panel

⚠️ Important: Never share your API keys, passwords, or other sensitive credentials in support tickets or public forums. Mask them before sharing any configuration files.

🔧 Troubleshooting Guide

🔧 Installation Issues

Blank White Page After Installation

Solution

500 Internal Server Error

Solution

CSS/JS Files Not Loading (404 Errors)

Solution

📧 Email Issues

Emails Not Being Sent

Solution

Emails Going to Spam

Solution

💳 Payment Problems

Payments Not Processing

Solution

Webhook Not Receiving Events

Solution

Subscription Not Activated After Payment

Solution

⚡ Performance Issues

Website Loading Slowly

Solution

High Server Memory Usage

Solution

🚫 Common Error Messages

"CSRF Token Mismatch"

Solution

"The page has expired due to inactivity"

Solution

"Failed to open stream: Permission denied"

Solution

"Class not found" Errors

Solution

🆘 Getting Help

Before Contacting Support

Contact Support

🔧 Troubleshooting Guide Complete!