Skip to main content

Troubleshooting

This guide covers common issues and their solutions when using XBuilder with Joomla.

Installation Issues​

Package Installation Fails​

Symptoms:

  • Error message during upload
  • Installation doesn't complete

Solutions:

  1. Check file being uploaded

    • Use pkg_xbuilder.zip (not the outer ZIP)
    • Don't extract the package before uploading

  2. Check PHP upload limits

    upload_max_filesize = 10M
    post_max_size = 12M

  3. Try alternative installation method

  4. Check permissions

    • /administrator/components should be writable
    • /modules should be writable
    • /media should be writable

PHP Version Error​

Message: PHP version must be at least 8.0.0

Solution:

  • Upgrade PHP to 8.0 or higher
  • Contact hosting provider if needed
  • Check System → System Information for current version

Joomla Version Error​

Message: Joomla version must be at least 4.0.0

Solution:

  • XBuilder requires Joomla 4.x, 5.x, or 6.x
  • Upgrade from Joomla 3 if necessary

Builder Interface Issues​

Builder Not Loading​

Symptoms:

  • Blank page when opening popup editor
  • Infinite loading spinner
  • JavaScript errors in console

Solutions:

  1. Clear browser cache

    • Hard refresh: Ctrl+Shift+R (Windows) / Cmd+Shift+R (Mac)
    • Or clear cache in browser settings

  2. Clear Joomla cache

    • System → Clear Cache → Delete all

  3. Check browser console

    • Press F12 → Console tab
    • Look for error messages

  4. Check for JavaScript conflicts

    • Disable other extensions temporarily
    • Test with a clean browser profile

  5. Verify file permissions

    /media/com_xbuilder/assets/ should be readable

  6. Try different browser

    • Test in Chrome, Firefox, or Edge
    • Update browser to latest version

Template Library Not Showing​

Symptoms:

  • Templates don't load
  • Empty template selection

Solutions:

  1. Wait for loading

    • Templates may take time to load
    • Check for loading indicators

  2. Check network tab

    • Press F12 → Network tab
    • Look for failed requests

  3. Check internet connection

    • Templates may load from CDN

  4. Clear cache and retry

Changes Not Saving​

Symptoms:

  • Click save but changes don't persist
  • Error on save

Solutions:

  1. Check popup has a title

    • Title is required for saving

  2. Check browser console for errors

    • Look for AJAX/fetch errors

  3. Verify CSRF token

    • Refresh the page and try again
    • Session may have expired

  4. Check server response

    • Network tab → find save request
    • Check response for error messages

  5. Verify permissions

    • User must have edit permission for popups

Module Display Issues​

Symptoms:

  • Module is set up but popup doesn't show
  • Works in admin but not frontend

Checklist:

  1. Module is published

    • Check Content → Site Modules
    • Status should be "Published"

  2. Module position is assigned

    • Position must be valid for your template

  3. Menu assignment is correct

    • Check which pages module is assigned to
    • Test on assigned pages

  4. Popup is published

    • Check Components → XBuilder → Popups
    • Status should be "Published"

  5. Publishing dates

    • Check Publish Up/Down dates
    • Ensure current date is within range

  6. Access level

    • Check module access level
    • Check popup access level
    • Verify user has access

  7. Clear cache

    • System → Clear Cache
    • Clear browser cache

  8. Check JavaScript console

    • F12 → Console
    • Look for errors

Solutions:

  1. Review menu assignment

    • Content → Site Modules → [Your Module]
    • Menu Assignment tab
    • Verify correct pages selected

  2. Check for multiple modules

    • Search for all XBuilder modules
    • Verify each module's assignment

  3. Clear cache

    • Menu assignment changes need cache clear

Wrong Popup Displaying​

Solutions:

  1. Verify popup selection

    • Edit the module
    • Check "Select Popup" field
    • Ensure correct popup is selected

  2. Check for multiple modules

    • Only one popup should be assigned per page
    • Review all XBuilder modules

Content Issues​

Images Not Loading​

Symptoms:

  • Broken image icons
  • Images missing in popup

Solutions:

  1. Verify image exists

    • Check Media Manager for the image
    • Confirm file path is correct

  2. Check file permissions

    • Images folder should be readable
    • Typically 644 for files, 755 for folders

  3. Check image format

    • Supported: JPG, PNG, GIF, WebP, SVG
    • Unsupported formats won't display

  4. Clear browser cache

    • Cached broken images may persist

  5. Check image path

    • Should start from /images/
    • Verify path in popup configuration

Embedded Article Not Showing​

Symptoms:

  • Article element is empty
  • "Article not found" message

Solutions:

  1. Verify article is published

    • Check Content → Articles
    • Status should be "Published"

  2. Check article access level

    • Article access should match popup viewers
    • Public for public popups

  3. Verify article ID

    • Confirm correct article is selected

  4. Check article isn't trashed

    • Trashed articles won't display

Embedded Module Not Rendering​

Symptoms:

  • Module area is blank
  • Module content missing

Solutions:

  1. Verify module is published

    • Check Extensions → Modules
    • Module should be enabled

  2. Check module ID

    • Confirm correct ID in XBuilder

  3. Verify module access level

    • Should match popup viewers

  4. Check for JavaScript conflicts

    • Some modules may conflict with popup

Performance Issues​

Builder Loads Slowly​

Solutions:

  1. Clear browser cache

    • Old cached files may cause issues

  2. Check browser extensions

    • Ad blockers may slow loading
    • Try incognito mode

  3. Check server performance

    • Monitor server response time
    • Consider server upgrade

  4. Optimize hosting

    • Use PHP OPcache
    • Enable gzip compression

Frontend Popup Loads Slowly​

Solutions:

  1. Optimize images

    • Reduce image file sizes
    • Use WebP format
    • Compress images before upload

  2. Reduce popup complexity

    • Fewer elements load faster
    • Remove unused elements

  3. Enable caching

    • Enable Joomla page cache
    • Enable browser caching

  4. Check for conflicts

    • Other extensions may slow loading

Browser-Specific Issues​

Safari Issues​

Symptoms:

  • Features not working in Safari
  • Display differences

Solutions:

  • Update Safari to latest version
  • Clear Safari cache
  • Check for Safari-specific console errors

Mobile Browser Issues​

Symptoms:

  • Popup displays incorrectly on mobile
  • Touch interactions not working

Solutions:

  • Test responsive settings in builder
  • Check mobile-specific trigger settings
  • Verify mobile breakpoint settings

Error Messages​

"CSRF Token Mismatch"​

Cause: Session expired or token invalid

Solution:

  1. Refresh the page
  2. Log out and log back in
  3. Clear browser cookies

"Permission Denied"​

Cause: User lacks necessary permissions

Solution:

  1. Check Components → XBuilder → Options → Permissions
  2. Verify user group has required permissions
  3. Check global permission settings

"Database Error"​

Cause: Database query failed

Solution:

  1. Check Joomla error logs
  2. Verify database connection
  3. Check database permissions
  4. Contact support with error details

Getting Help​

Information to Collect​

Before contacting support, gather:

  1. Environment info

    • Joomla version
    • PHP version
    • XBuilder version
    • Browser and version

  2. Error details

    • Exact error message
    • Screenshot of the issue
    • Browser console errors (F12 → Console)

  3. Steps to reproduce

    • What you were doing
    • What you expected
    • What happened instead

Support Resources​

  • Documentation — Check relevant docs sections
  • FAQ — Review frequently asked questions
  • Support Forum — Search for similar issues
  • Contact Support — With collected information

Debug Mode​

Enable Joomla debug for more information:

  1. System → Global Configuration → System
  2. Set "Debug System" to Yes
  3. Reproduce the issue
  4. Note any additional error messages
  5. Disable debug mode after troubleshooting

Quick Fixes Checklist​

Common fixes that solve most issues:

  • Clear Joomla cache (System → Clear Cache)
  • Clear browser cache (Ctrl+Shift+R)
  • Refresh the page
  • Log out and log back in
  • Check component/module is published
  • Verify menu assignment
  • Check access levels
  • Check browser console for errors
  • Try a different browser
  • Disable other extensions temporarily

Next Steps​