Troubleshooting

Start here when something is wrong with a site you run yourself. Take the four first steps below, then follow the symptom to the page that has the answer. This page is for whoever runs the server. If you are a choir's admin and the site is hosted by us, see Get help instead.

First steps for anything

1. Run the configuration check. It prints the settings the server would use and lists every problem it can see:

   node --env-file=choirmaster.env scripts/check-config.js

   Or npm run config:check where the settings are already in the environment, or docker compose exec app npm run config:check in Docker. See Check your configuration. Fix everything it lists first: most problems are there.

2. Read the start-up log. The first lines tell you the version, the [config] warnings, whether the database was reached and whether the server is listening. See Logs and health checks.

3. Ask the health address. curl -s http://localhost:3001/api/health should answer {"status":"ok", ...} with the version you expect. No answer means the process is not running or not reachable.

4. Look at the Updates page. Log in as an Admin or Site Admin and open /admin/updates. Its red and blue banners say whether the licence key, the update check or the last install has a problem.

Find your symptom

What you see	Go to
Settings in my .env file are ignored	The site will not start, or ignores my settings
The log says dist/ not found: serving the API only	The site will not start, or ignores my settings
The log says failed to start:	The site will not start, or ignores my settings
The site starts but the data is missing or in an odd place	The site will not start, or ignores my settings
A new feature is missing after a Cloudflare update	The site will not start, or ignores my settings
A shared link, or a search result, shows "Choir" or the wrong name, description or picture	The site will not start, or ignores my settings
On Cloudflare, every page answers {"success":false,"error":"Not Found"}	The site will not start, or ignores my settings
On Cloudflare, pages appear but have no content and nobody can log in	The site will not start, or ignores my settings
The browser keeps showing the old version	The site will not start, or ignores my settings
Nobody stays logged in	Nobody can log in, or emails do not arrive
The admin login always fails	Nobody can log in, or emails do not arrive
A login link never arrives	Nobody can log in, or emails do not arrive
A login link goes to the wrong address or gives an error	Nobody can log in, or emails do not arrive
Contact form messages do not arrive	Nobody can log in, or emails do not arrive
"Security verification failed"	Nobody can log in, or emails do not arrive
Some announcement emails are not sent on Cloudflare	Nobody can log in, or emails do not arrive
Announcements will not send, and the log says SITE_URL is not set	Nobody can log in, or emails do not arrive
An upload fails, or a file is "too large"	Uploads fail, or updates misbehave
S3 PUT failed: 403 or 404	Uploads fail, or updates misbehave
There is no Update now button	Uploads fail, or updates misbehave
An update failed, or the site went back by itself	When an update fails
"Registered to another website"	Your licence key
An update disappeared after I recreated a container	Uploads fail, or updates misbehave
The footer link will not switch off	Uploads fail, or updates misbehave

Where to get help

• Community edition. It is free and comes without support. The software and this guide are what you have. Updates are offered as they are released, but none is promised.
• Standard edition. Support is part of the Standard edition, as described when you buy it. See Community and Standard editions.
• Licence keys. Moving a key to a new website and replacing a lost key are done by support, whatever your edition: write to support@choirmastercms.com. See Your licence key.
• Before you write, have the version number (shown on the Updates page and by /api/health), how you run the site (Node, Docker or Cloudflare), the output of the configuration check with the secrets as they are (they are masked) and the relevant lines of the log.