When it will not start

Work down this page in order. The first three sections cover most of what actually goes wrong.

It starts and then stops

Check the log first. It almost always names the cause.

In the log	Cause	Fix
`EADDRINUSE`	Something already has port 3000, 4000 or 443	Find it (`netstat -ano` on Windows, `ss -ltnp` on Linux). On Windows Server, IIS binds 443 by default
`ENOENT` on a `.pem` or `.pfx` path	The certificate path does not exist, or the service account cannot read it	Check the path. Remember the service runs as a different account
`ECONNREFUSED` to 5432	PostgreSQL is not running, or `DATABASE_URL` points at the wrong host	Start the database. On Docker, `docker compose ps`
`password authentication failed`	Wrong password in `DATABASE_URL`	Compare against what the database actually has
A Prisma migration error	The schema is from a different version	See migrations below
`Administrator rights are required`	Not elevated	Use `sudo`, or an elevated shell on Windows

Nothing answers on the port

Is the process running? ./plugboard service-status, systemctl status plugboard, or docker compose ps.
Is it listening? ss -ltnp | grep -E '3000|4000', or netstat -ano | findstr "3000 4000".
Is a firewall in the way? Test from the machine itself first with curl http://localhost:3000. If that works and remote does not, it is network, not application.
Is the reverse proxy pointing at the right place? A proxy configured for localhost will not reach a container. A proxy configured for a container name will not reach a host process.

The browser loads but everything fails

CORS errors in the console

PUBLIC_URL (or WEB_URL) does not match the address in the address bar. https://x, https://x/ and http://x are three different values. Fix it and restart.

`Unknown tenant`

The Host header does not match a tenant’s primaryDomain, and the first hostname label is not a tenant slug either. On a single-tenant install, set DEFAULT_TENANT_SLUG. On a custom domain, set the tenant’s primaryDomain. See your own domain.

401 on everything after signing in

Usually a clock problem. Tokens are time-bound, and a server whose clock has drifted rejects its own freshly issued tokens. Run NTP.

If JWT_SECRET was changed, everybody is logged out by design. Sign in again.

The console loads but never updates

A proxy is buffering /api/events/*. Turn buffering off for that path. See HTTPS and certificates.

Migrations will not apply

Migrations are forward-only and idempotent, so re-running is safe. The failures that happen are:

The database already has a newer schema than the application. You rolled the image back without restoring the database. Restore the dump taken before the update.

A migration failed halfway. The dump the update script took in step 2 is the way back. Restore it, then investigate before trying again.

Permissions. The database user needs to create tables. A user granted only SELECT and INSERT on existing tables cannot migrate.

Apply them by hand if you need to:

node scripts/plugboard.mjs migrate

Connectors fail after a restore

Every connector reports a decryption error and nothing authenticates.

SECRETS_MASTER_KEY does not match the one in use when the backup was taken. The data is fine; the vault cannot be opened. Set the correct key and restart.

If the key is genuinely lost, the credentials are not recoverable. Reconfigure each connector from its source system. This is the failure the backups page exists to prevent.

HTTPS problems

Symptom	Cause
“HTTPS not started” in the log	Wrong certificate path, or wrong PFX password. The log names the file it tried
Browser warns about the certificate	Self-signed, or the intermediate chain is missing. Set `TLS_CA_FILE`
Works on a desktop, fails on Android	Missing intermediate chain. Same fix
Cannot bind 443	On Linux, reinstall the service so the capability is granted to the right account. On Windows, something else has the port
Let’s Encrypt never issues	Port 80 unreachable from the internet, so the HTTP-01 challenge fails. Use a tunnel or a DNS-01 challenge

Updates

Symptom	Cause
Updates never arrive	`AUTO_UPDATE` is off, or the machine cannot reach the update endpoint. `./plugboard update --check` says which
Update refuses with a checksum mismatch	The download was corrupted or tampered with. It is meant to refuse. Try again
Update reported success but the version did not change	A tag resolved to the old image. Pin a digest
The service did not come back after an update	Check the log. The previous version is in `.previous-version` if you need to go back

Email is not being sent

Is there an email connector configured and enabled? Nothing sends until there is one. See SMTP.
Is it in demo mode? Demo mode does not send.
Did the test connection pass? Run Save and test on the connector.
Is the message switched off? Some templates can be disabled. See email messages.
Is the link wrong rather than the send failing? Then it is PUBLIC_URL, not email.

Modules gate navigation. If a section is missing, its module is off, or your role lacks the permission, or your licence tier does not include it. Check in that order:

Admin, Features. Is the module enabled?
Admin, Roles. Does your role hold the permission?
Admin, Licence. Does your plan include the module?

Slow

Endpoint protection scanning the data directory. The usual answer on Windows. Exclude .pgdata or the Docker volume.
Audit log size. Set a retention policy. See audit and retention.
A connector timing out. A screen that waits on a slow MDM feels like the application is slow. Check the connector’s test connection latency.
Disk. A nearly full volume makes PostgreSQL crawl before it fails.

Collecting information for support

If you need to raise something, this is what makes it answerable on the first reply:

curl -s https://helpdesk.yourschool.org/api/health/version

Plus: which install method, which operating system, the last hundred lines of the log around the failure, and what changed immediately before it started. That last one solves it more often than anything else on this page.