Skip to content

Earn 30% on every license you refer. Join the affiliate program

$349
Get it · $349 Try demo
Sign in

Common issues.

Solutions to common problems.

Sep 16, 2026

This guide covers common problems and their solutions.

Start here

Check the affected page and note the error message. If you can sign in as an administrator, open the Health Center for configuration warnings.

A problem can depend on application code, account data, settings, or hosting. You do not need to identify the cause before contacting support.

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.

Ask your host to check ownership and permissions for the PHP process. The correct user and permission settings depend on the server. See Server requirements.

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 required for OTP login, new user verification, and password resets. If email delivery isn't working, OTP sign-in won't work and many users (especially members) won't be able to access the platform.

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 against your provider's settings. See Email configuration for production setup.
  2. Try common ports:
    • 587 for TLS (most common)
    • 465 for SSL
  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. Use the encryption and port pair specified by your email provider. Do not disable encryption to work around a connection error.

"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 set up
  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
[email protected]
MAIL_FROM_NAME=Your App Name

For Gmail testing and production provider setup, use the email configuration guide.

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
  • Missing SPF, DKIM, or DMARC DNS records
  • Low sender reputation

Solutions:

  1. Use an email address from your own domain ([email protected])
  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. Sign in as admin and check for migration prompts.

"Specified key was too long" during installation

If you see an error like Specified key was too long; max key length is 1000 bytes during installation, your database server is using a non-standard storage engine (usually Aria or MyISAM) instead of InnoDB.

This happens on some shared hosting providers (especially on CloudLinux / cPanel) that override the default MariaDB or MySQL storage engine. Reward Loyalty requires InnoDB for proper database functionality.

Fix:

Open config/database.php and change 'engine' => null to 'engine' => 'InnoDB' for your database connection:

'mysql' => [
    // ... other settings ...
    'engine' => 'InnoDB',
],

'mariadb' => [
    // ... other settings ...
    'engine' => 'InnoDB',
],

Then:

  1. Confirm this is a new installation with no business or member data.
  2. Ask your host to provide an empty database that uses InnoDB.
  3. Restart the installation with that database.

Existing installation: Do not delete its tables or installation marker. Back up the installation and contact support for the specific error.

💡 Note: InnoDB is the standard engine for MySQL 5.7+ and MariaDB 10.3+ and is enabled on nearly all hosting providers. This setting ensures your database uses it instead of a less capable alternative.

Refreshing after updates

If the application behaves unexpectedly after an update:

php artisan optimize:clear

Run this from the application directory with the PHP version your installation uses. It clears Laravel application caches; it does not remove member balances or transactions.

Plesk: Updates failing or incomplete

If you're using Plesk and the in-app updater seems to fail with no message or updates don't apply as expected, the issue is often a PHP version mismatch between web and CLI.

Symptoms

The application log (storage/logs/laravel.log) shows PHP discovery messages like these (the update runner itself writes its steps to storage/logs/updater.log):

UPDATE: FPM binary detected, searching for CLI equivalent
UPDATE: Testing FPM-derived path {"path":"/opt/plesk/php/8.4/sbin/php8.4","works":false}
UPDATE: FPM CLI equivalent not found, falling through to PATH search
UPDATE: Found suitable PHP binary {"path":"/opt/plesk/php/8.5/bin/php"}

The problem

Plesk has PHP 8.4 FPM enabled for your website (handling web requests), but PHP 8.4 CLI is not installed. The updater falls back to a different PHP version (e.g., 8.5), causing:

  • Version mismatch: The update process runs with a different PHP version than your web app
  • Silent failures: Background processes may fail or behave unexpectedly
  • Cache issues: OPcache for PHP 8.4 FPM isn't cleared by PHP 8.5 CLI commands

Solution

In Plesk, ensure both PHP-FPM and PHP CLI use the same version:

  1. Sign in to Plesk and navigate to your domain
  2. Go to PHP Settings or PHP Version
  3. Check that PHP CLI is enabled for the same version as your website
  4. If PHP 8.4 CLI is not available, contact your hosting provider to install it

Alternatively, you can verify CLI availability via SSH:

# Check which PHP CLI versions are available
ls -la /opt/plesk/php/*/bin/php

# Test if your expected version works
/opt/plesk/php/8.4/bin/php --version

After fixing

Once CLI and FPM versions match, run the updater again.

PHP extension missing (CLI vs FPM mismatch)

If the dashboard updater fails with "extension not available" but the hosting panel shows the web extension is enabled, you're likely hitting a CLI vs FPM configuration mismatch.

💡 Quick fix: If you can't resolve this, use the Manual File Replacement process instead. It bypasses CLI entirely.

Common example: ZipArchive

Your update logs (storage/logs/updater.log) show:

Step 1/7: Extracting package...
ERROR: ZipArchive extension not available

The hosting panel can still show the extension enabled for web requests.

The problem

Most hosting environments manage two separate PHP configurations with independent extension settings:

Configuration Used By Where to Check
PHP-FPM Web requests to your website Hosting panel
PHP CLI Background scripts, updates, artisan commands SSH terminal

Many hosting setups have extensions enabled for FPM but not CLI. This affects any feature that runs via command line, including:

  • In-app updates (uses CLI to avoid web request timeouts)
  • Scheduled tasks / cron jobs
  • Artisan commands
  • Queue workers

Solution by hosting panel

Plesk

  1. Go to Tools & Settings → PHP Settings
  2. Select your PHP version (e.g., PHP 8.4)
  3. Switch to the CLI tab (not CGI/FPM)
  4. Enable the required extension (e.g., zip, intl, gd)
  5. Click OK to save

cPanel

  1. Go to MultiPHP INI Editor
  2. Select your domain
  3. Enable the required extension
  4. Note: Some extensions require EasyApache configuration. Contact your host

DirectAdmin / other panels

Contact your hosting provider to enable extensions for PHP CLI. Most panels have separate CLI and FPM configurations that need to match.

VPS / manual setup

Edit the CLI php.ini:

# Find CLI php.ini location
php --ini

# Compare CLI vs FPM extensions
php -m                           # CLI extensions
 # Check web PHP extensions in the hosting panel; do not expose phpinfo publicly.

# Common locations:
# CLI: /etc/php/8.4/cli/php.ini
# FPM: /etc/php/8.4/fpm/php.ini

💡 Tip: The CLI and FPM php.ini files are often in different directories. Enabling an extension in one doesn't enable it in the other.

Workaround (bypass CLI entirely)

If you cannot modify CLI PHP settings, use the Manual File Replacement process. You download the latest version, upload the files via FTP or your hosting file manager, and restore your data. No CLI or exec() required.

Slow performance

If the application runs slowly, especially on Plesk or shared hosting, the issue is often related to PHP's OPcache or memory limits.

Quick fix (SSH required)

Run the Laravel optimization command with increased memory:

php -d memory_limit=512M artisan optimize

This pre-compiles and caches configuration, routes, and views. This can help when missing application caches cause the slowdown. If it does not help, check the Health Center and ask your host to review resource usage.

💡 Note: You may need to re-run this command after updates or when you change .env settings.

Optional: PHP settings (Plesk / cPanel)

Ask your host to size PHP workers and OPcache for the available memory and measured load. A worker count copied from another server can exhaust memory. Use the hosting panel for changes, then check response times and error logs.

PWA not installing

Progressive Web App (PWA) features require HTTPS in production. Reward Loyalty uses the browser's built-in "Add to Home Screen" functionality. There is no custom install prompt.

Symptoms

  • "Add to Home Screen" option doesn't appear in your browser menu
  • Browser doesn't recognize the site as installable

Solution

  1. Verify HTTPS: Your URL must start with https://
  2. Check for mixed content: All resources (images, scripts) must load over HTTPS
  3. Test manually: In Chrome, open DevTools → Application → Manifest to see validation errors

💡 Note: PWA works on http://localhost for local development.

How to install

Use your browser's built-in installation option:

  • Chrome (Android/Desktop): Menu → "Install app" or "Add to Home Screen"
  • Safari (iOS): Share button → "Add to Home Screen"

Available controls depend on the device and browser. Use the online website if installation is unavailable.

See PWA Configuration for detailed setup instructions.

Offline access not working

Members report they can't see their loyalty cards offline.

Causes

  • Card was never viewed while online (nothing to cache)
  • Browser cleared cached data
  • Unsupported browser

Solution

  1. View cards online first: QR codes are cached on first view
  2. Install the PWA: Installing to home screen improves offline reliability
  3. Check browser: PWA works on Chrome, Safari, Firefox, and Edge. Internet Explorer is not supported.

Testing offline mode

  1. Visit a loyalty card while connected
  2. Enable airplane mode
  3. Reopen the loyalty platform
  4. Verify the QR code displays with an "offline" banner

Store integration issues

Diagnose orders not earning points, connection failures, and webhook errors from the integration's own dashboard. The Overview tab shows connection and webhook status at a glance. The Activity tab lists recent webhook deliveries and the reason an event was ignored.

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