Troubleshooting

Troubleshooting

🔍 Step 1: Check Your Logs (Fastest Solution!)

Most problems can be self-diagnosed by examining logs! Start here:

For ChurchCRM Administrators (Easiest)

Built-in Log Viewer - No file access needed:

1. Log in to ChurchCRM as an admin user
2. Go to Admin → System Logs
3. View logs directly in the web interface
4. Filter by log level (DEBUG shows the most details)
5. Look for ERROR or CRITICAL entries

For Shared Hosting (cPanel)

Access via cPanel File Manager or FTP:

1. Log in to your cPanel control panel
2. Navigate to File Manager or use FTP/SFTP
3. Find your ChurchCRM directory (usually public_html/churchcrm)
4. Navigate to the logs/ subdirectory
5. Download today's -app.log file (named like 2025-11-17-app.log)
6. Open in a text editor and look for [ERROR] or [CRITICAL] lines

For Self-Hosted/VPS (SSH Access)

Access via SSH:

# Navigate to ChurchCRM logs
cd /var/www/vhosts/churchcrm/logs/
# View today's log (replace date)
tail -100 2025-11-17-app.log
# or search for errors
grep ERROR 2025-11-17-app.log

Apache Error Logs

If ChurchCRM logs don't show the issue:

• Shared Hosting (cPanel): Check cPanel → Error Log (usually in Main section)
• Self-Hosted/VPS: grep ERROR /var/log/apache2/error_log (or /var/log/httpd/error_log)

See Logging and Diagnostics guide for detailed log information.

Step 2: Check Known Issues

We encourage all problems to be tracked in GitHub issues. If you're having difficulties, someone else probably has too!

When you open an issue on GitHub:

• An auto-comment will appear with diagnostic collection tips
• Follow the guidance in that comment to help us help you faster

Check these issue categories:

• Installation / Upgrade
• Platform: Self Hosted
• Platform: Shared Hosting
• Platform: Database