Skip to main content

Troubleshooting

This guide covers common issues you may encounter when installing, configuring, or running Open Core Business Suite, along with their solutions.

Installation Issues​

Composer Install Fails​

Error: Memory limit exhausted

PHP Fatal error: Allowed memory size of 134217728 bytes exhausted

Solution: Increase the PHP memory limit:

# Run Composer with increased memory
php -d memory_limit=-1 $(which composer) install --ignore-platform-reqs

Or update your php.ini:

memory_limit = 512M

Error: Platform requirements not met

Your requirements could not be resolved to an installable set of packages.

Solution: Use the --ignore-platform-reqs flag:

composer install --ignore-platform-reqs

This is safe when your server meets the minimum PHP version requirement (PHP 8.4+) but may have slightly different extension versions.

Error: Package not found / authentication required

Solution: Ensure Composer 2.x is installed and up to date:

composer self-update

npm Install or Build Fails​

Error: npm install runs out of memory

FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory

Solution: Use the optimized build command designed for servers with limited RAM:

npm run build:server:optimized

For very low memory servers, create a swap file first:

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Then build
npm run build:server:optimized

Error: Node.js version too old

Solution: Install Node.js 18 or higher:

# Check current version
node -v

# Install via NodeSource (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Permission Errors During Installation​

Error: Permission denied when writing to storage or bootstrap/cache

Solution (VPS):

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

Replace www-data with your web server's user (e.g., nginx, apache, nobody).

Solution (cPanel):

  1. In File Manager, right-click the storage folder
  2. Select Change Permissions and set to 775
  3. Repeat for bootstrap/cache

Server Errors​

500 Internal Server Error​

A 500 error is a generic server error. The specific cause is in the log files.

Step 1: Check the Laravel log

tail -50 storage/logs/laravel.log

On cPanel, use File Manager to navigate to storage/logs/ and open laravel.log.

Step 2: Enable debug mode temporarily

In your .env file, set:

APP_DEBUG=true

Reload the page to see the detailed error message. After identifying and fixing the issue, set APP_DEBUG=false again.

warning

Never leave APP_DEBUG=true in production. It exposes sensitive configuration details including database credentials.

Step 3: Check common causes

CauseSolution
Missing .env fileCopy .env.example to .env and configure it
Missing APP_KEYRun php artisan key:generate
Missing JWT_SECRETRun php artisan jwt:secret
Wrong file permissionsSet storage/ and bootstrap/cache/ to 775
Missing vendor/ directoryRun composer install --ignore-platform-reqs
Missing PHP extensionsInstall required extensions (see System Requirements)

Blank White Page​

A blank page typically means PHP encountered a fatal error but error display is off.

  1. Enable debug mode: Set APP_DEBUG=true in .env
  2. Check PHP error logs: 
    # VPS with PHP-FPM
    tail -f /var/log/php-fpm/error.log

    # Apache
    tail -f /var/log/apache2/error.log

    # cPanel - check Error Log in cPanel dashboard
  3. After identifying the error, set APP_DEBUG=false

403 Forbidden Error​

Cause: The web server cannot access the public directory.

Solution for Nginx: Verify the root directive points to the /public folder:

root /var/www/html/public;

Solution for Apache: Ensure mod_rewrite is enabled and .htaccess is present in the public/ folder:

sudo a2enmod rewrite
sudo systemctl restart apache2

404 Not Found on All Routes​

Cause: URL rewriting is not working.

Solution for Apache:

  1. Ensure mod_rewrite is enabled
  2. Verify AllowOverride All is set in your virtual host: 
    <Directory /var/www/html/public>
        AllowOverride All
    </Directory>
  3. Restart Apache: sudo systemctl restart apache2

Solution for Nginx: Ensure the try_files directive is configured:

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

Database Issues​

Database Connection Errors​

Error: SQLSTATE[HY000] [2002] Connection refused

  1. Verify the database server is running: 
    sudo systemctl status mysql
  2. Check .env database settings: 
    DB_HOST=127.0.0.1
    DB_PORT=3306
    DB_DATABASE=your_database
    DB_USERNAME=your_user
    DB_PASSWORD=your_password
  3. On shared hosting, the database host may be localhost or a specific IP provided by your host
  4. Ensure the database user has been granted privileges on the database

Error: SQLSTATE[HY000] [1045] Access denied

  1. Verify the database username and password in .env are correct
  2. On cPanel, ensure the user is added to the database with All Privileges via MySQL Databases

Migration Errors​

Error: Table already exists

This can happen if migrations were partially run. Check migration status:

php artisan migrate:status

If you need a fresh start (this will delete all data):

php artisan migrate:fresh --force

Error: Foreign key constraint violation during migration

This usually means modules are being migrated out of order. The setup commands handle this automatically:

# For production
php artisan opencorebs:live --fresh

# For development
php artisan opencorebs:demo --fresh

These commands run migrations in the correct dependency order.

Email Delivery Issues​

Email settings are configured through the admin panel Settings page, not the .env file.

Emails Not Sending​

  1. Navigate to Settings in the admin panel
  2. Review the SMTP configuration:
    • Mail Driver: smtp
    • Host: Your SMTP server (e.g., smtp.gmail.com, smtp.mailgun.org)
    • Port: Usually 587 (TLS) or 465 (SSL)
    • Username: Your SMTP username
    • Password: Your SMTP password
    • Encryption: tls or ssl (must match the port)
    • From Address: A valid email address
    • From Name: Your organization name
  3. Click Send Test Email to verify delivery

Common SMTP Issues​

IssueSolution
Gmail blocks sign-inUse an App Password instead of your regular password
Connection timeoutCheck if your hosting provider blocks outbound SMTP ports (25, 465, 587)
Authentication failedVerify the username and password are correct in Settings
Emails going to spamSet up SPF, DKIM, and DMARC records for your domain

Queue-Based Email Delivery​

If QUEUE_CONNECTION is set to database or redis in your .env file, emails are sent via background jobs rather than immediately. Ensure the queue worker is running:

# Check if the queue worker is running
ps aux | grep "queue:work"

# Start the worker
php artisan queue:work --sleep=3 --tries=3

For production, use Supervisor to keep the worker running. See the Installation guide for Supervisor configuration.

If QUEUE_CONNECTION=sync, emails are sent immediately during the request (no worker needed, but slower page loads).

Frontend / Asset Issues​

CSS or JavaScript Not Loading​

  1. Check if built assets exist:

    Look for the public/build/ directory. If it is missing or empty, assets need to be compiled:

    npm install
    npm run build

  2. Check the storage symlink:

    php artisan storage:link

  3. Verify .htaccess is present in the public/ directory (Apache only)

  4. Clear browser cache -- cached old assets can cause layout issues after an upgrade

  5. Check for mixed content warnings -- if your site uses HTTPS, ensure APP_URL in .env starts with https://

Assets Not Updating After Changes​

Clear the Laravel view and cache:

php artisan optimize:clear

Then hard-refresh your browser (Ctrl+Shift+R or Cmd+Shift+R).

Module / Addon Issues​

Module Not Appearing After Installation​

  1. Check that the module folder exists in Modules/ (e.g., Modules/Payroll/)
  2. Verify module.json exists inside the module folder
  3. Check modules_statuses.json in the application root -- the module should be listed and set to true
  4. Regenerate the Composer autoloader: 
    composer dump-autoload
  5. Clear caches: 
    php artisan optimize:clear

Module Enable/Disable Not Working​

Via Admin Panel:

  1. Navigate to Addons (accessible at /addons)
  2. Find the module and toggle its status
  3. If the toggle does not respond, check storage/logs/laravel.log for errors
  4. Verify the modules_statuses.json file has write permissions (set to 664)

Via Command Line:

# Enable a module
php artisan module:enable ModuleName

# Disable a module
php artisan module:disable ModuleName

Module Migration Fails​

Run the migration for the specific module with verbose output:

php artisan module:migrate ModuleName --force

If the error references a missing table from another module, that module may need to be migrated first. The setup commands handle dependency ordering automatically:

php artisan opencorebs:live

(Without --fresh, this runs pending migrations without dropping existing tables.)

Mobile App Connection Issues​

App Cannot Connect to Server​

  1. Verify the server URL -- the app must connect to your APP_URL (e.g., https://yourdomain.com)
  2. Check HTTPS -- mobile apps require a valid SSL certificate. Self-signed certificates will cause connection failures
  3. Test the API endpoint -- open https://yourdomain.com/api/V1/ in a browser to confirm the API is accessible
  4. Check CORS settings -- if the app gets blocked by CORS, review your server configuration

Push Notifications Not Working​

  1. Verify Firebase is configured correctly (see Installation - Firebase Setup)
  2. Ensure the google-services.json file is placed in the app's android/app/ directory
  3. Check that Firebase Cloud Messaging is enabled in the Firebase Console
  4. Verify the queue worker is running (notifications are sent via background jobs)

Location Features Not Working in App​

  1. Verify the Google Maps API key is configured in Settings > Map Settings in the admin panel
  2. Ensure the required Google APIs are enabled (Maps SDK for Android, Geocoding API)
  3. For the mobile app, verify the API key is also set in android/app/src/main/AndroidManifest.xml
  4. Check that the user has granted location permissions on their device

Queue and Background Job Issues​

Jobs Stuck in Queue​

  1. Check if the queue worker is running: 
    ps aux | grep "queue:work"
  2. Check for failed jobs: 
    php artisan queue:failed
  3. Retry failed jobs: 
    php artisan queue:retry all
  4. If using Supervisor, check its status: 
    sudo supervisorctl status

Jobs Not Processing at All​

  1. Verify QUEUE_CONNECTION in .env:
    • sync -- jobs run immediately (no worker needed)
    • database -- requires php artisan queue:work to be running
    • redis -- requires Redis and php artisan queue:work
  2. For database driver, ensure the jobs table exists: 
    php artisan migrate --force
  3. Start or restart the worker: 
    php artisan queue:restart
    php artisan queue:work --sleep=3 --tries=3

Cache Issues​

Stale Data or Configuration​

Clear all application caches:

php artisan optimize:clear

Configuration Changes Not Taking Effect​

After modifying .env:

php artisan config:clear

If you use configuration caching in production:

php artisan config:cache

Route Changes Not Reflecting​

php artisan route:clear

Performance Issues​

Slow Page Load Times​

  1. Enable caching in production: 
    php artisan config:cache
    php artisan route:cache
    php artisan view:cache
  2. Use database or Redis queue instead of sync for background jobs
  3. Check slow queries by enabling the query log in storage/logs/laravel.log
  4. Ensure debug mode is off: APP_DEBUG=false in .env

High Memory Usage​

  1. Set an appropriate PHP memory limit in php.ini: 
    memory_limit = 256M
  2. If queue workers consume too much memory, add the --memory flag: 
    php artisan queue:work --memory=128
    This restarts the worker when it exceeds the specified memory (in MB).

WebSocket / Real-Time Issues​

Laravel Reverb Not Connecting​

  1. Verify Reverb configuration in .env: 
    REVERB_APP_ID=your_app_id
    REVERB_APP_KEY=your_app_key
    REVERB_APP_SECRET=your_app_secret
    REVERB_HOST="0.0.0.0"
    REVERB_PORT=8080
  2. Ensure the Reverb server is running: 
    php artisan reverb:start
  3. Check that the Reverb port (default 8080) is open in your firewall
  4. For production behind a reverse proxy (Nginx), configure WebSocket proxying: 
    location /app {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }

Artisan Commands Not Working​

On cPanel / Shared Hosting​

  1. Use the full PHP path: 
    /usr/local/bin/php artisan migrate --force
  2. Check if Terminal is available in your cPanel dashboard
  3. Contact your hosting provider to enable SSH access
  4. As an alternative, set up a scheduled cron job in cPanel to run artisan commands

Command Not Found​

Ensure you are in the application root directory (where artisan is located):

cd /var/www/html   # VPS
cd ~/public_html   # cPanel
php artisan --version

Common Error Reference​

ErrorLikely CauseSolution
500 Internal Server ErrorMissing .env, bad permissions, PHP errorCheck storage/logs/laravel.log, enable APP_DEBUG=true temporarily
SQLSTATE[HY000] [2002]Database server not running or wrong hostVerify DB credentials in .env, check MySQL is running
SQLSTATE[42S02] Table not foundMigrations not runRun php artisan migrate --force
Class not foundAutoloader not updatedRun composer dump-autoload
The stream or file ... permission deniedStorage not writableSet storage/ and bootstrap/cache/ to 775
419 Page ExpiredCSRF token mismatchClear browser cookies, check SESSION_DOMAIN in .env
TokenMismatchExceptionSession expiredIncrease SESSION_LIFETIME in .env
Route [login] not definedRoute cache is staleRun php artisan route:clear
Vite manifest not foundAssets not builtRun npm install && npm run build
Blank page with no errorFatal PHP error before outputCheck PHP error logs, enable APP_DEBUG=true

Getting More Help​

Gather Diagnostic Information​

When contacting support, include:

  1. PHP version: php -v
  2. Laravel log excerpt: Last 50 lines of storage/logs/laravel.log
  3. Server type: cPanel, VPS, Cloud, etc.
  4. Web server: Apache or Nginx
  5. Steps to reproduce the issue

Support Channels​

Last updated on