Troubleshooting

The problems that come up most often, and what to do.

Where to look first

Quran CMS keeps no log files of its own. What it records is in the admin panel: Scheduled jobs → Log (every job run, with its answer or error), Settings → E-mail → Recent e-mails, Messages → Spam (each held message with its reason) and Social Auto Post → Post log. PHP errors go to your host's error log; in cPanel, look for Errors or a file named error_log in the site's folder.

A white page or "500 Internal Server Error"

Errors are hidden from visitors. To see the message, edit config.php and change

define('QC_DEBUG', false);

to true. Reload the page, note the file and line, and set it back to false straight away.

The usual causes:

• PHP is too old (7.4 is the least, 8.1 or newer is best), or PDO MySQL, cURL or mbstring is missing. cPanel → Select PHP Version.
• A plugin breaks a page. Rename its plugin.php (to plugin.php.off, say) by FTP and the site forgets the plugin. Renaming the folder is not enough.
• A half-finished update. Extract the update ZIP again, then open /db_update.php.

"Headers already sent", or you cannot stay signed in

Something is printed before the page starts. Almost always config.php was saved with a byte-order mark (BOM), or with spaces or empty lines before <?php. Remove anything before <?php and save it as UTF-8 without BOM.

Licence messages

The admin sidebar shows the state of the licence. Admin → License → Check now asks license.faruk.bd again.

While the licence is not in order, visitors see This website is temporarily unavailable while its licence is renewed, and the admin panel opens only the licence page. Signing in, Admin → License, db_update.php and the cron keep working, so you can always put it right.

A server without a certificate store cannot reach the licence site over HTTPS; ask the host to fix it. Meanwhile define('QC_LICENSE_INSECURE_SSL', true); in config.php skips the certificate check. Set it back to false afterwards.

Scheduled jobs do not run

Admin → Scheduled jobs says when the jobs last ran. If they have not run, copy the line from that page again (in cPanel the five stars go into the time fields, only the rest into Command), and check PHP path for the cron line. A web cron that answers Invalid cron key. uses an old address. See Scheduled jobs.

E-mails are not sent

1. Admin → Settings → E-mail: choose SMTP, fill in the mailbox details, save, then Send test e-mail. A failure says Sending failed: with the reason; Recent e-mails keeps it too.
2. From e-mail should be an address on your own domain. For Gmail, use an app password.
3. An e-mail whose template is switched off is never sent.

Share pictures or the prayer banner are not drawn

The server draws pictures with PHP's GD extension with FreeType. Without it, ayah share pictures can still be drawn in your browser: Settings → Share images → Draw pictures in this browser, left open while it works. The daily prayer-times banner of Social Auto Post can only be drawn by the server. Without GD, uploaded pictures are also kept at full size instead of being made smaller.

Things that need the internet

If the host blocks outgoing connections, ask for these to be allowed:

• The weather on the mosque screen: api.open-meteo.com. If the server cannot reach it, switch off Let this site fetch the weather under Settings → Prayer times; screens then ask the service themselves.
• The translation voice and the speaking Arabic letters: Microsoft's voice service (speech.platform.bing.com), or Azure with a key under Settings → Media studio. Test it there with Listen: 1:2 in Bengali.
• Hadith import: cdn.jsdelivr.net and raw.githubusercontent.com.
• The licence: license.faruk.bd.

The home page works, every other address says 404

Clean addresses need URL rewriting.

• Apache or LiteSpeed: the file .htaccess must be in the site's folder. File managers hide names that start with a dot; switch on Show hidden files and upload it again from the ZIP. For a site in a sub-folder, set RewriteBase in it, for example RewriteBase /quran/.
• nginx: add the rules from the nginx part of README.md to the server block.

The admin panel lives in real files under /admin/, so it opens even while rewriting is broken.

An upload is refused

• The file is larger than the server allows (…): raise upload_max_filesize and post_max_size in cPanel → MultiPHP INI Editor.
• Your session has expired. Please reload the page and try again. after a big upload usually means the whole form was bigger than post_max_size.
• Some uploads have their own limit: blog pictures 8 MB, fonts 15 MB.

I forgot the admin password

• Forgot password? on the sign-in page (/forgot-password) e-mails a link that works for one hour.
• Another administrator can set a new one under Admin → Users → Edit → Password.
• With SSH, make a new hash with php -r "echo password_hash('NewPassword', PASSWORD_DEFAULT);" and paste it into the password field of your row in the qc_users table with phpMyAdmin.

After eight sign-in tries in ten minutes the page says Too many attempts. Please wait a few minutes.

Still stuck

Open a ticket from your account on license.faruk.bd with the site's address, what you did, and the error shown with QC_DEBUG on.