Common Issues

This guide covers frequently encountered problems and their solutions.

Error 500 (Server Error)

A 500 error means something went wrong on the server. To diagnose:

1. Check the log file: storage/logs/laravel.log
2. Look for the most recent error entry
3. The error message often indicates the cause

Common Causes

Missing PHP Extension: Especially ext-intl (Internationalization). Ensure all required extensions are enabled.

File Permissions: The storage/ and bootstrap/cache/ directories must be writable by the web server.

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

Environment File Missing: Ensure .env exists and contains valid configuration.

Directory Listing Instead of App

If you see a folder structure instead of the application:

Missing .htaccess

Some operating systems hide files starting with a dot. On macOS, press Cmd + Shift + . to show hidden files. Ensure .htaccess was uploaded.

mod_rewrite Disabled

Apache's mod_rewrite module must be enabled. Contact your hosting provider if unsure.

Image Upload Problems

If images fail to upload:

1. Check that proc_open and proc_close PHP functions are enabled
2. Verify the public/files directory is writable
3. Check upload size limits in php.ini

Email Configuration Issues

Email is essential for Reward Loyalty—without working email, users cannot log in due to the passwordless OTP authentication system.

During Installation

The installation wizard includes a test email feature to verify your configuration before completing setup. If you encounter errors:

"Cannot connect to the mail server"

Cause: Server address or port is incorrect.

Solution:

1. Verify the SMTP host is correct (e.g., smtp.gmail.com)
2. Try common ports:
   • 587 for TLS (most common)
   • 465 for SSL
   • 25 for unencrypted (often blocked)
3. Check if your hosting provider blocks outbound email ports
4. Verify your server has internet access

"Invalid username or password"

Cause: Credentials are incorrect.

Solution:

• For Gmail: You must use an App Password, not your regular Gmail password
  1. Enable 2-Step Verification in Google Account settings
  2. Go to Security → App passwords
  3. Generate a new app password for "Mail"
  4. Use the 16-character code in the password field
• For other providers: Verify username and password are correct
• Check for typos or extra spaces when copying credentials

"The mail server refused the connection"

Cause: Server is blocking the connection or port is wrong.

Solution:

1. Try switching between port 587 (TLS) and 465 (SSL)
2. Check your server's firewall settings
3. Verify SMTP access is enabled for your email account
4. Contact your hosting provider about outbound email restrictions

"Connection timed out"

Cause: Network issue or server is unreachable.

Solution:

1. Check your internet connection
2. Verify the SMTP server is online and responding
3. Wait a few minutes and try again
4. Check if your hosting provider blocks outbound connections on email ports

"Security error"

Cause: SSL/TLS encryption mismatch.

Solution:

1. Try switching encryption settings:
   • Port 587 usually requires TLS
   • Port 465 usually requires SSL
2. If both fail, try None (not recommended for production)
3. Verify your email provider's recommended settings

"The server rejected the email"

Cause: Sender address not authorized.

Solution:

1. Use an email address from a verified domain
2. For Mailgun/SES: Verify the sender domain in your account dashboard
3. For SMTP: Ensure the "from" address matches your authenticated account
4. Check your email provider's sender authentication requirements

"Mail relay not permitted"

Cause: Server doesn't allow sending from this address.

Solution:

1. Verify the "from" address is authorized by your email provider
2. Ensure SMTP authentication is properly configured
3. Check that your username matches the "from" address
4. Contact your email provider about relay permissions

Test Email Sent But Not Received

If the test shows success but you don't receive the email:

1. Check spam/junk folder — Test emails often get filtered
2. Wait 2-3 minutes — Email delivery can be delayed
3. Verify the email address — Check for typos in the test email field
4. Try a different email — Test with another email provider
5. Check email provider settings — Some providers block automated emails

After Installation

If emails aren't working after installation completes:

Check Configuration:

Verify your email settings in .env:

MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=your-username
MAIL_PASSWORD=your-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@example.com
MAIL_FROM_NAME=Your App Name

For Gmail SMTP:

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

Check Logs:

Review storage/logs/laravel.log for specific error messages. The log will show detailed information about why emails are failing.

Emails Going to Spam

If system emails consistently land in spam folders:

Possible causes:

• Using a free email address (Gmail, Yahoo, etc.) as the sender
• Email address domain doesn't match your application domain
• Missing SPF, DKIM, or DMARC DNS records
• Low sender reputation

Solutions:

1. Use an email address from your own domain (noreply@yourdomain.com)
2. Configure SPF records to authorize your email server
3. Set up DKIM signing for email authentication
4. Add a DMARC policy to your domain
5. Consider using a transactional email service (Mailgun, SES, Postmark, Resend)
6. Consult your email hosting provider's documentation

Development Options

For local development, use these options instead of production email:

Mailpit:

• Catches all emails locally without sending them
• View emails at http://localhost:8025
• Requires Mailpit running locally
• Set MAIL_MAILER=mailpit in .env

Log File:

• Writes full email content to storage/logs/laravel.log
• No setup required
• Set MAIL_MAILER=log in .env

⚠️ Warning: Never use development drivers in production. Mailpit and Log drivers don't send real emails.

Database Errors

Connection Refused

Verify database credentials in .env:

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

Table Not Found

Database migrations may not have run. Log in as admin and check for migration prompts.

Refreshing After Updates

If the application behaves unexpectedly after an update:

php artisan optimize:clear

This clears all cached data and forces a fresh load.

Still Stuck?

If these solutions don't help:

1. Note the exact error message
2. Check storage/logs/laravel.log for details
3. Visit the Support page for help options