When it will not start

Work down this page in order. The first three sections cover most failures.

Use platform-specific examples only for a build actually installed and validated on that host. Current native release packaging targets Linux x64; Windows/macOS examples are reference-launcher guidance, not promises of published packages.

It starts and then stops

Check the log first. It usually 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	The database is not running, or DATABASE_URL points at the wrong host	Restart from the status panel
password authentication failed	Wrong password in DATABASE_URL	Compare it against what the database holds
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

1. Is the process running? ./plugboard service-status, systemctl status plugboard.
2. Is it listening? ss -ltnp | grep -E '3000|4000', or netstat -ano | findstr "3000 4000".
3. 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.
4. 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.

There is no command to apply them by hand, and you do not need one. Every start applies whatever is pending, so once the cause above is fixed, restarting is the retry.

Nobody can sign in

Every administrator is locked out: the identity provider is down, the person who held the only local account has left, or an SSO domain was saved with a typo.

The way back is a command on the machine. We hold no key into a server you run yourself, so this needs somebody with a shell on the box.

Two steps, from the install directory. First, ask what accounts exist:

./plugboard admin-reset

It prints every active account, marking any that have no password set. Then name the one you want:

./plugboard admin-reset [email protected]

It tells you whose password is about to change and asks you to type the address a second time to confirm. Then it asks for the new password twice. Twelve characters is the minimum, and it stops without changing anything if the two do not match.

The reset is written to your audit log as admin.reset.local, against the account that changed, recording the address and that it came from the command line.

Once you are back in, turn on multi-factor authentication under Account, and if SSO was the cause, fix the domain before you rely on it again. See single sign-on.

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 lost, the credentials cannot be recovered. 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

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

Nothing appears in the navigation

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

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

Slow

• Endpoint protection scanning the data directory. The usual answer on Windows. Exclude .pgdata in the install directory.
• 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

Send it to [email protected]. Include:

• Your version, from Admin, Licence.
• Which install method and which operating system.
• The last hundred lines of the log around the failure.
• What changed immediately before it started. This one answers more cases than anything else on this page.

The diagnostics report from the status panel gathers most of that for you in one file.