Maintenance
Troubleshooting
Common symptoms, why they happen, and where to fix them. Every row here traces back to a real code path covered in more detail on the pages it links to — start there if the short version below isn't enough.
| Symptom | Cause | Fix |
|---|---|---|
| Site shows a maintenance page instead of the dashboard | A file named updating.lock exists at the install root. Zender
checks for it on every single request and, if it's there, serves a maintenance
page and stops — nothing else on the site runs while it's present.
Nothing in the automatic updater creates or removes this file for you (see
Updating); it's a switch you flip yourself for
manual maintenance work. |
Delete updating.lock from the install root once you're done. If you
didn't create it yourself and don't know why it's there, check with whoever has
server access before deleting it — someone may be mid-update. |
| Blank page after installing | A fatal PHP error before anything renders. The two most common causes:
PHP older than 8.4 (bundled libraries require up to 8.4.1 — see
Requirements), or an incomplete vendor/ upload, since Zender
can't start at all if that folder (or anything inside it) is missing. |
Check your server's PHP error log for the actual fatal error, confirm your PHP
version is 8.4, and re-upload vendor/ in full — it's a
large directory and partial uploads are the most common cause of this. |
| "Invalid Database Credentials!" during install | The installer throws this message for any connection failure, not just a wrong host or port — in practice the usual cause is that the database doesn't exist yet, or already has tables in it. | Create an empty database first, and make sure the database user
has CREATE and INSERT privileges on it. See
Installation for the full form walkthrough. |
| The API reference page (Docs → API) is blank | Fixed in 3.10.0 — earlier versions loaded the Redoc viewer from a CDN, which fails outright with no internet access reaching that CDN. | Nothing to do on 3.10.0 and later: Redoc is now vendored locally and renders offline (see REST API). If you still see a blank page on this version, it's a different fault — check the browser console rather than assuming it's the CDN issue again. |
| Scheduled SMS/WhatsApp messages never send | Cron isn't configured. Without something calling the sms.scheduled
and wa.scheduled endpoints, due sends just sit queued
indefinitely — Zender has no background process of its own that
dispatches them. |
Set up the crontab entries described on the Cron jobs
page, using your site's real system_token. |
| A WhatsApp account keeps unlinking | The WhatsApp server process died (crashed, was killed, or the host rebooted) and didn't come back. The binary does not restart itself. | Run it under a process supervisor (systemd on Linux, launchd on macOS) instead of launching it directly, so it's restarted automatically — see WhatsApp server. |
| Uploads fail (contacts, media, samples, imports…) | The web server user doesn't have write access to wherever Zender is trying to save the file. | Make sure the uploads folder and the cache, compiled-template, and temporary folders under system storage are all writable by the web server user — see Configuration. |
| An update "appears to do nothing" | The update handler reports zip-extraction and SQL-import failures to your installation's error log — but stays silent on file-copy and cleanup failures, and on a response that never made it back to your browser. | Check the error log first. If it's empty, see Updating for exactly which failures are (and aren't) logged, and what to check instead. |