Troubleshooting Update Issues

Common issues and solutions

1. "Update page not showing" : No redirect to update page

Symptom: You uploaded new files but the admin panel doesn't redirect to the update page.

Possible causes:

• The new config/larapen/version.php file was not uploaded correctly.
• Configuration cache is stale.

Solution:

1. Verify the file config/larapen/version.php exists and contains the new version number.
2. Clear the config cache. If you have SSH access:

   php artisan config:clear
   php artisan cache:clear

3. If you don't have SSH access, try deleting the file bootstrap/cache/config.php via your File Manager.
4. Log out and log back in to the admin panel.

2. "500 Internal Server Error" after uploading files

Symptom: The website shows a 500 error after uploading new files.

Possible causes:

• Incomplete file upload (some files missing or corrupted).
• PHP version incompatibility.
• File permissions issue.

Solution:

1. Check your server's PHP error log for specific error messages.
2. Re-upload all files from the release archive, ensuring the upload completes without errors.
3. Verify your PHP version meets the requirements listed in the changelog.
4. Check file permissions: directories should be 755, files should be 644.
5. If the problem persists, restore from your backup and contact support.

3. "Update failed" error during the update process

Symptom: The update process shows a failure message for a specific version.

Solution:

1. Note the exact error message and version number.
2. Check the Laravel log file at storage/logs/laravel.log for detailed error information.
3. Common causes:
   • Database permission issue: The database user may lack privileges to create/alter tables. Grant full privileges.
   • Disk space: Ensure your server has sufficient free disk space.
   • MySQL version: Some migrations may require MySQL 8.0+. Check your MySQL version.
4. After fixing the issue, try the update again. The system will resume from the version that failed.
5. If the problem persists, restore from backup and contact support with the error details.

4. Blank page or missing styles after update

Symptom: The website loads but appears unstyled or blank.

Solution:

1. Clear all caches:
   • Admin panel: Settings → Cache → Clear All Caches
   • Or via SSH: php artisan cache:clear && php artisan config:clear && php artisan view:clear
2. Rebuild theme assets: Appearance → Themes → Build All
3. Hard-refresh your browser: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac).
4. Check the browser console (F12) for JavaScript or CSS loading errors.

5. "Class not found" or "Method not found" errors

Symptom: PHP class or method errors after updating.

Solution:

1. Regenerate the Composer autoload files. Via SSH:

   composer dump-autoload

2. If you don't have SSH access, look for an autoload_classmap.php regeneration option in your hosting panel, or contact your hosting provider.
3. Ensure all files were uploaded correctly; incomplete uploads can cause missing classes.

6. Update stuck or timeout

Symptom: The update process seems to hang or times out.

Solution:

1. Do NOT click "Update" again; a lock prevents concurrent updates.
2. Wait a few minutes for the lock to expire (5 minutes).
3. If the update still doesn't complete, try running it via SSH:

   php artisan larapen:update --force

4. If the lock is stuck, clear it:

   php artisan cache:clear

   Then retry the update.

7. Add-on not detected after update

Symptom: An add-on doesn't appear in the admin panel or its features are missing after update.

Solution:

1. Go to Add-ons in the admin panel and verify the add-on is listed and activated.
2. Click "Sync" to re-scan the extensions directory.
3. Check that the add-on files are in the correct directory: extensions/addons/{addon-name}/
4. Verify the addon.json file exists and is valid JSON.

8. Locked out after wrong settings (CAPTCHA, mail, etc.)

Symptom: Incorrect settings entered in the admin panel prevent you from logging in (e.g., wrong CAPTCHA keys, broken mail configuration).

Solution — Option 1: Force .env values (temporary):

1. Add the following line to your .env file:

   SETTINGS_FORCE_ENV=captcha

   This tells the system to ignore database settings for that group and use .env values instead.

2. If config caching is enabled, run: php artisan config:clear
3. Log in and fix the settings in the admin panel.
4. Remove the SETTINGS_FORCE_ENV line from .env once fixed.

Available group names: general, social_auth, geoip, cache, queue, captcha, ai, translator, currency_exchange, mail, sms, cookie_consent, locale. Use all to skip all database overrides.

Solution — Option 2: Reset via CLI (permanent):

1. Connect to your server via SSH.
2. Run the following command to disable the problematic setting:

   php artisan settings:reset captcha_enabled

3. You can also target specific keys:

   php artisan settings:reset captcha_driver --value=none
   php artisan settings:reset login_captcha_enabled

The command auto-detects *_enabled keys and defaults to disabling them (setting the value to 0). It also clears the settings cache automatically.

When to contact support

If none of the above solutions resolve your issue:

1. Restore from your backup to get back to a working state.
2. Gather the following information:
   • The error message (screenshot or text)
   • The contents of storage/logs/laravel.log (last 100 lines)
   • Your PHP version (php -v)
   • Your MySQL version
   • The version you're updating from and to
3. Open a support ticket with these details.