Common Issues.

This guide covers frequently encountered problems and their solutions.

Types of "Bugs"

Before reporting an issue, it's helpful to understand what kind of problem you're facing. In our experience, reported issues fall into two categories:

1. Code Bugs (The Software)

These are actual errors in the Reward Loyalty code.

• Characteristics: They happen to everyone, regardless of hosting. The features simply cause an error or produce the wrong result.
• Fix: We fix these in official updates.

2. Environment Bugs (The Server)

These are issues caused by your specific hosting environment, not the software itself.

• Characteristics: The software works for others but fails for you. Caused by missing PHP extensions, incorrect file permissions, strict firewall rules, disabled functions (like exec or symlink), or misconfigured database settings.
• Fix: You (or your server admin) must configure the server correctly.

💡 Pro Tip: To eliminate most environment bugs, use a hosting provider optimized for Laravel, such as Laravel Forge. Shared hosting often blocks necessary features or has outdated configurations that cause "phantom bugs".

Support & Patience

We always help resolve issues related to the environment to the extent possible, but we ask for your patience.

Please understand that providing support for unique server configurations comes on top of the immense effort required to create and maintain this product—development, design, marketing, copywriting, documentation, and creating updates. Creating a professional $69 product involves literally 1,000+ hours of work.

We are committed to helping you succeed, but debugging specific hosting environments takes time away from core development.

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

For Gmail SMTP:

MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
[email protected]
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 ([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. Log 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 (typically 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. Drop all database tables via phpMyAdmin (select all → drop)
2. Delete the file storage/installed if it exists
3. Run the installation again

💡 Note: InnoDB is the standard engine for MySQL 5.7+ and MariaDB 10.3+ and is enabled on virtually all hosting providers. This setting simply 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

This clears all cached data and forces a fresh load.

Plesk: Updates Failing or Incomplete

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

Symptoms

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

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. Log 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 one-click updater fails with "extension not available" but your phpinfo.php shows the extension is enabled, you're likely hitting a CLI vs FPM configuration mismatch.

💡 Quick fix: If you can't resolve this, use the Manual Update 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

But visiting a phpinfo.php test file in your browser confirms the zip extension is loaded.

The Problem

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

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 directly:

# Find CLI php.ini location
php --ini

# Compare CLI vs FPM extensions
php -m                           # CLI extensions
curl yoursite.com/phpinfo.php    # FPM extensions (create this file first)

# 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 Update process. This uploads and extracts the update package via FTP or your hosting file manager—no CLI required. It's a reliable workaround while you sort out the server configuration.

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. After running this command, the application should return to normal speed.

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

Optional: PHP Settings (Plesk / cPanel)

For sustained performance on Plesk, cPanel, or similar control panels, apply these settings at the domain level in your PHP configuration.

OPcache Settings (php.ini):

opcache.enable=1
opcache.enable_cli=0
opcache.memory_consumption=192
opcache.interned_strings_buffer=16
opcache.max_accelerated_files=40000
opcache.revalidate_freq=2
opcache.validate_timestamps=1
opcache.jit=0

PHP-FPM Pool Settings:

If your server uses PHP-FPM (most VPS and Plesk setups do), these settings help manage concurrent requests:

pm=dynamic
pm.max_children=25
pm.start_servers=6
pm.min_spare_servers=6
pm.max_spare_servers=12
pm.max_requests=500
request_terminate_timeout=120s
php_admin_value[memory_limit]=256M

⚠️ Where to apply: In Plesk, navigate to your domain → PHP Settings. In cPanel, look for PHP Selector or MultiPHP Manager. If unsure, contact your hosting provider.

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"
• Firefox: Menu → "Install"

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

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