Skip to main content

​
🛠️ Troubleshooting Guide

If you’re running into issues with the LucentUI theme, don’t worry! Here’s a list of common problems and how to resolve them.

​
🚫 Theme Not Rendering / Blank Page

Symptoms:
  • Page is blank or not styled
  • Header/footer is missing
Possible Causes:
  • Theme not properly installed or not selected
  • Missing required assets or build step not completed
  • Base URL not set correctly
  • themes/lucentui/Theme.php is malformed (e.g. missing comma, invalid array) or not found
Fixes:
  • Make sure LucentUI is selected as the active theme in Paymenter settings
  • Run php artisan app:settings:change app_url to set the Base URL
  • Build the theme again using npm run build lucentui from your Paymenter root
  • Check the theme folder path: should be /themes/lucentui
  • Validate your Theme.php using an online PHP linter

​
⚠️ npm/Vite Build Errors

Symptoms:
  • Errors when running npm run build lucentui
  • Missing dependencies or modules Possible Causes:
  • Node.js or NPM not installed or outdated
  • Missing package.json or node_modules Fixes:
  • Ensure you have Node.js v14+ and NPM installed
  • Run npm install in your Paymenter root to install dependencies
  • Check for typos in package.json
  • Try deleting node_modules and running npm install again

​
⚠️ Error 500 - Internal Server Error

Symptoms:
  • Page displays error 500 or “SERVER ERROR”
Possible Causes:
  • Syntax error in theme files
  • PHP version incompatibility
  • Laravel cache issues
Fixes:
  • Run php artisan config:clear, php artisan view:clear, and php artisan cache:clear
  • Check storage/logs/laravel.log for exact error trace
  • Ensure you’re using PHP 8.3 or higher (as required by Paymenter)

​
🧩 Theme Settings Not Showing

Symptoms:
  • Custom theme settings are missing in the admin panel
Possible Causes:
  • Theme.php file not loaded properly
  • Syntax error in one of the setting definitions
Fixes:
  • Double check Theme.php syntax (especially commas, quotes, brackets)
  • Refresh the admin dashboard or relogin
  • Re-import the theme

​
🖼️ Background Image Not Showing

Symptoms:
  • Background image set in settings does not appear
Possible Causes:
  • Invalid URL format
  • Image is blocked due to CORS
Fixes:
  • Make sure the image URL is direct and ends with .jpg, .png, etc.
  • Try uploading the image to a CDN or your own server
  • Ensure browser isn’t blocking external content

​
🎨 Color Settings Not Applying

Symptoms:
  • Primary or secondary colors are not updating
Possible Causes:
  • Cache not cleared
  • Incorrect hsl() format
Fixes:
  • Check that all colors are valid (e.g. hsl(240, 100%, 50%))
  • Clear browser cache or use hard reload (Ctrl + F5)
  • Try clearing views: php artisan view:clear

​
🔧 Custom JS/CSS Not Working

Symptoms:
  • Custom scripts or styles have no effect
Possible Causes:
  • Syntax errors in your custom code
  • Content-Security-Policy (CSP) blocking inline scripts
Fixes:
  • Wrap CSS in <style> and JS in <script> (automatically done if using theme settings)
  • Avoid using document.write in JS
  • Check browser console for errors (F12 > Console)
Symptoms:
  • Footer text or other markdown content displays as raw text
Fixes:
  • Ensure you’re not escaping special characters (like *, _)
  • Wrap content correctly — avoid unclosed tags

​
🧪 Still Broken?

Checklist:
  • ✅ Is the theme installed in the right folder?
  • ✅ Is your Paymenter version up to date?
  • ✅ Are you using supported PHP version?
  • ✅ Did you clear Laravel & browser cache?
  • ✅ Did you check the logs?
🧠 Pro Tip: Always test new settings on a staging environment before applying them live!
Need help? Open a ticket in our Discord Server!