Skip to content

Troubleshooting FAQ

Jump to bottom
Brent Cordis edited this page Feb 11, 2026 · 2 revisions

Troubleshooting FAQ

Common troubleshooting scenarios and solutions for the Proclaim Joomla component.

Installation & Setup

PHP Version Requirements

Problem: Error message appears across all admin pages: "Your host needs to use PHP 8.3.0 or higher to run CWM-Proclaim."

Solution:

  • Proclaim requires PHP 8.3.0 or higher
  • Contact your hosting provider to upgrade PHP to at least version 8.3.0
  • After upgrading, clear your browser cache and reload the admin panel
  • The warning is displayed by the System - Proclaim plugin on all backend pages when PHP version is below minimum

Why this matters: Proclaim uses modern PHP features that are only available in PHP 8.3+. Running on older versions will cause fatal errors.

Missing Database Tables or Data

Problem: Blank pages, missing content, or errors about tables not existing after installation or migration.

Solution: Run the Proclaim Assets utility to rebuild database structure:

  1. Go to Components → Proclaim → Administration
  2. Click the Assets tab
  3. Click Check Assets to verify
  4. Click Fix Assets to rebuild asset records and permissions
  5. Check the Database tab and run Check Tables and Fix Tables if needed

When to use:

  • After fresh installation
  • After restoring from backup
  • When you see permission errors
  • When items don't appear that should be visible

First-Time Setup Steps

After installing Proclaim for the first time:

  1. Run Assets Fix

    • Go to Components → Proclaim → Administration → Assets
    • Click Fix Assets to ensure proper ACL permissions

  2. Create a Menu Item

    • Go to Menus → Main Menu → Add New Menu Item
    • Menu Item Type: Proclaim → Sermon List
    • Save the menu item

  3. Configure Component Options

    • Go to Components → Proclaim → Options (toolbar button)
    • Set default template, date formats, and items per page
    • Configure permissions for user groups

  4. Create Your First Content

    • Add a Teacher (Components → Proclaim → Teachers)
    • Add a Message/Sermon (Components → Proclaim → Messages)
    • View it on the frontend via your menu item

Templates & Display

Template Not Showing on Frontend

Problem: Created a template but content doesn't display on the frontend.

Solution:

  1. Create a menu item - Templates don't display automatically:

    • Go to Menus → Main Menu → Add New Menu Item
    • Select Proclaim → Sermon List as the menu item type
    • In the menu item options, select your custom template
    • Save and view the frontend

  2. Check template status - Ensure template is Published:

    • Go to Components → Proclaim → Templates
    • Verify your template status is "Published"

  3. Check access level - Ensure template access matches your user group:

    • Edit the template
    • Verify the Access Level (Public, Registered, etc.)

How to Change Colors and Styles

Problem: Want to customize the appearance of Proclaim output.

Solution:

Method 1: Template Settings

  1. Go to Components → Proclaim → Templates
  2. Edit your template
  3. Find color settings:
    • Back Color - Background color
    • Front Color - Text color
    • Light Color - Accent/border colors
  4. Use the color picker or enter hex codes (e.g., #1a3867)
  5. Save and refresh frontend

Method 2: Custom CSS

  1. Go to your template's Advanced tab
  2. Add custom CSS in the Custom CSS field
  3. Or add CSS to your Joomla template's custom.css file

Legacy color format: Older backups may have 0x prefix (e.g., 0xFF0000). The component automatically converts these to standard hex format (#FF0000) when displaying.

Custom Template Code Not Appearing

Problem: Created custom template code but it doesn't show on the frontend.

Solution:

  1. Assign template code to template:

    • Go to Components → Proclaim → Templates
    • Edit your template
    • In the Layout Editor tab, ensure your custom code is selected
    • Save the template

  2. Assign template to menu item:

    • Go to Menus and edit your Proclaim menu item
    • In the menu item options, select your template
    • Save the menu item

  3. Check template code status:

    • Go to Components → Proclaim → Template Codes
    • Verify your template code is Published
    • Verify the Type matches your template's type (1=Messages, 2=Teachers, etc.)

Media Files

Media Files Not Playing

Problem: Audio or video files won't play on the frontend.

Possible Solutions:

1. Check Server Configuration

  • Go to Components → Proclaim → Servers
  • Verify the server type is correct (Local, URL, YouTube, etc.)
  • For local files, verify the Path field points to the correct directory
  • Click Test Connection if available

2. Check File Paths

  • Go to Components → Proclaim → Media Files
  • Edit the media file
  • Verify the Filename or Path is correct
  • For local files, the path should be relative to your Joomla root or the server path
  • For URLs, ensure the full URL is entered correctly

3. File Format Issues

  • Verify the media file format is supported by browsers:
    • Audio: MP3, OGG, WAV
    • Video: MP4, WebM, OGG
  • Check the MIME Type field is correct (e.g., audio/mpeg for MP3)

4. Server Permissions

  • Ensure your web server can read the media files (typically 644 permissions for files, 755 for directories)
  • Check that the directory isn't protected by .htaccess rules

YouTube Videos Not Embedding

Problem: YouTube videos don't display or embed properly.

Solution:

1. Check Server Type

  • Go to Components → Proclaim → Servers
  • Create or edit a server
  • Set Server Type to YouTube
  • Save the server

2. Check URL Format

  • Go to Components → Proclaim → Media Files
  • Edit the media file
  • For YouTube URLs, use one of these formats:
    • https://www.youtube.com/watch?v=VIDEO_ID
    • https://youtu.be/VIDEO_ID
    • Or just the video ID: VIDEO_ID
  • Select the YouTube server in the Server dropdown
  • Save the media file

3. Check Link Type

  • In the Media File edit screen, verify Link Type is set appropriately
  • For embedded playback, use Direct Link or Web Link

4. Content Security Policy (CSP)

  • If enabled, CSP headers may block YouTube embeds
  • Go to Components → Proclaim → Options
  • Check the CSP Extra Sources setting
  • YouTube is allowed by default, but verify no conflicts exist

Backup & Restore

How to Create/Restore Backups

Creating a Backup:

  1. Go to Components → Proclaim → Administration → Backup tab
  2. Choose export method:
    • Download Backup - Downloads .sql file to your computer (recommended for off-site storage)
    • Save Backup to Server - Saves to /media/com_proclaim/backup/ (quick snapshots)
  3. Click the appropriate button
  4. The backup includes all database content but NOT media files

Restoring a Backup:

  1. Go to Components → Proclaim → Administration → Backup tab
  2. Scroll to the Import section
  3. Choose import method:
    • Upload Backup File - Upload a .sql or .zip file from your computer
    • Import from Backup Folder - Select a previously saved backup from the dropdown
    • Advanced: Tmp Folder - For large files uploaded via FTP
  4. Click Import and wait for completion
  5. After restore, run Fix Assets (Administration → Assets tab)

What's Included in a Backup

Included (Database Only):

  • Messages (sermons/studies)
  • Teachers
  • Series
  • Topics
  • Locations
  • Media file records (metadata only)
  • Servers
  • Podcasts
  • Templates and template codes
  • Comments
  • All configuration settings

NOT Included (Must backup separately):

  • Uploaded images
  • Audio files
  • Video files
  • Thumbnail images
  • Any files in /media/com_proclaim/

For Complete Migration:

  1. Export database backup via Proclaim
  2. Copy /media/com_proclaim/ folder via FTP/file manager
  3. On new server: Install Proclaim, import backup, copy media folder
  4. Run Fix Assets from Administration → Assets

Performance

Slow Loading with Many Messages

Problem: Pages load slowly when you have hundreds or thousands of messages.

Solutions:

1. Enable Query Caching in Joomla

  • Go to System → Global Configuration → System
  • Set Cache to ON - Conservative Caching
  • Set Cache Handler to File (or Redis/Memcached if available)

2. Database Indexes (Proclaim 10.1.0+)

  • Database indexes are created automatically on installation
  • If upgrading from older versions, indexes are added during migration
  • Key indexed fields: studytitle, studydate, published, access

3. Limit Items Per Page

  • Go to Components → Proclaim → Options
  • Set Items per Page to a reasonable number (10-20)
  • Users can navigate with pagination

4. Use Filters Wisely

  • Enable frontend filters for teacher, series, or topic
  • This allows users to narrow results without loading everything

5. Optimize Images

  • Compress thumbnail images before uploading
  • Use appropriate image sizes (don't upload 4000x3000 for 200x200 thumbnails)

Large Media Files

Problem: Large audio/video files slow down your site or use too much bandwidth.

Solutions:

1. External Hosting (Recommended)

  • Use YouTube, Vimeo, or SoundCloud for video/audio
  • Create a Server with type YouTube, Vimeo, etc.
  • Add media files with external URLs
  • Benefits: No bandwidth usage, no storage limits, built-in player

2. CDN Integration

  • Upload media files to a CDN (Amazon S3, CloudFlare, etc.)
  • Create a Server with type URL
  • Set the server path to your CDN URL
  • Add media files with CDN URLs

3. Local Storage Optimization

  • Store large files outside your public_html in a protected directory
  • Use Proclaim's server path configuration to access them
  • Serve files via PHP script to control access/bandwidth

4. Compress Media Files

  • Use audio compression for sermons (64-128kbps is often sufficient for voice)
  • Use video compression (H.264, moderate bitrate)
  • Consider offering multiple quality options

Common Errors

"Session Expired" on Save

Problem: When saving a message, teacher, or other item, you see "Invalid Token" or "Session Expired" error.

Causes:

  • CSRF token timeout (Joomla security feature)
  • Taking too long to fill out the form
  • Multiple browser tabs/windows open to the same edit form

Solutions:

  1. Save more frequently - Click Save periodically while editing long content
  2. Copy content before saving - Select and copy your text before clicking Save, in case the save fails
  3. Increase session lifetime:
    • Go to System → Global Configuration → System
    • Increase Session Lifetime from 15 to 30 or 60 minutes
  4. Don't open multiple edit tabs - Edit one item at a time
  5. Check for browser extensions - Ad blockers or privacy extensions may interfere with tokens

Blank Page After Install

Problem: White screen or blank page after installing Proclaim.

Possible Causes & Solutions:

1. PHP Version Too Low

  • Proclaim requires PHP 8.3.0+
  • Check your PHP version in System → System Information → PHP Information
  • Contact your host to upgrade to PHP 8.3 or higher

2. Check Error Logs

  • Enable error reporting: System → Global Configuration → Server → Error Reporting = Maximum
  • Check Joomla error log: System → Maintenance → Error Logs
  • Check server error logs (in your hosting control panel, often in logs/error_log)
  • Look for fatal errors, parse errors, or memory limit exceeded

3. Memory Limit

  • Proclaim may require more memory for large sites
  • Increase PHP memory_limit to at least 256M
  • Check current limit in System → System Information
  • Contact your host or edit php.ini

4. Missing PHP Extensions

  • Required: PDO, JSON, Zlib, MBString, XML
  • Check System → System Information → PHP Information

"Item Not Found" or "Access Denied"

Problem: Frontend shows "Item not found" or "You are not authorized to view this resource."

Solutions:

1. Check Publication Status

  • Edit the item (Message, Teacher, Series, etc.)
  • Verify Status is set to Published
  • Check Start Publishing and Finish Publishing dates

2. Check Access Levels

  • Edit the item
  • Verify Access Level (Public, Registered, etc.) matches your user group
  • If logged out, only Public access items are visible

3. Run Assets Fix

  • Go to Components → Proclaim → Administration → Assets
  • Click Fix Assets to rebuild permissions
  • This is especially important after restore/migration

4. Check Menu Item Access

  • Edit your Proclaim menu item
  • Verify the menu item Access Level allows your user group

Rate Limit Exceeded (Proclaim 10.1.0+)

Problem: Message appears: "You have submitted too many requests. Please wait X seconds."

Cause:

  • The system plugin enforces rate limiting to prevent rapid form submissions
  • Default: 10 POST requests per 60 seconds

Solutions:

1. Wait and Retry

  • Wait for the specified time period
  • Then try your action again

2. Adjust Rate Limiting (Administrators only):

  • Go to Components → Proclaim → Options
  • Find Rate Limit Max (default: 10) and Rate Limit Window (default: 60 seconds)
  • Increase the max or window as needed
  • Set Rate Limit Max to 0 to disable rate limiting entirely

When you might see this:

  • Batch operations on many items
  • Repeated save attempts after validation errors
  • Testing/development work

Migration & Compatibility

Migrating from an Older Version

Problem: Want to migrate from Joomla 3 Bible Study to Joomla 5.1+ Proclaim.

Solution:

  1. Backup your Joomla 3 site completely (database + files)
  2. Create a backup using the old component's backup feature
  3. Set up Joomla 5.1+ on your new server/environment
  4. Install Proclaim (latest version)
  5. Import your backup:
    • Go to Components → Proclaim → Administration → Backup
    • Use the Import section to upload your old backup
    • Database migrations run automatically
  6. Copy media files - Transfer /media/com_proclaim/ folder via FTP
  7. Run Assets Fix - Go to Administration → Assets and click Fix Assets
  8. Review templates - Check template settings and update if needed
  9. Test thoroughly - Verify all content displays correctly

Version Compatibility:

  • Backups from version 9.0 and later are supported
  • Older backups may require intermediate steps
  • If you see "Old DB" or "Not Current DB" warnings, your backup may be too old

After Migration: Missing Media Files

Problem: After importing a backup, media file records exist but files won't play.

Solution:

  • Database backups do NOT include actual files (audio, video, images)
  • You must manually copy the /media/com_proclaim/ directory:
    1. On old server: Download /media/com_proclaim/ via FTP
    2. On new server: Upload to /media/com_proclaim/ via FTP
    3. Check file permissions (644 for files, 755 for directories)
  • Update server paths if directory structure changed:
    • Go to Components → Proclaim → Servers
    • Edit each server and verify the Path field

Help Resources

If you can't find a solution here:

  1. Documentation - https://github.com/Joomla-Bible-Study/Proclaim/wiki
  2. Community Forum - https://www.christianwebministries.org/forum.html
  3. GitHub Issues - https://github.com/Joomla-Bible-Study/Proclaim/issues
  4. Email Support - info@christianwebministries.org

When reporting issues, please include:

  • Proclaim version (check Components → Proclaim → Control Panel)
  • Joomla version
  • PHP version
  • Description of the problem
  • Steps to reproduce
  • Any error messages from logs

Getting Started

Guides

Development

Help Screens

Clone this wiki locally