Run and maintain

Troubleshooting and FAQ

Outcome: you can match what you see to a cause and fix it without contacting support.

Start with the health check. Most problems show up there first.

The health check

Open https://your-domain/api/health.

What you see	What it means	Fix
`{"ok":true,"db":"connected","migrations":"up to date"}`	Everything is fine.	Nothing.
`{"ok":true,"db":"connected","migrations":"behind"}`	The database is reachable but is missing migrations from this version.	See Migrations behind.
`{"ok":false,"db":"unavailable","migrations":"behind"}` (HTTP 503)	The app cannot reach PostgreSQL.	Check `DATABASE_URL`: host, port, user, password and database name. Percent-encode special characters in the password (`@` is `%40`). Hosted databases usually need `?sslmode=require` at the end. Check that PostgreSQL is running.
An error page, a blank page, or the browser cannot connect	The app is not running.	Look at the application log (cPanel: the log file named in Setup Node.js App; Render: Logs; Vercel: the deployment's logs). The last lines say why it stopped.

Migrations behind

Your files are newer than your database. Either:

set MIGRATE_ON_START=true and restart the app, so migrations run on start, or
run pnpm db:migrate from the application folder with DATABASE_URL set.

Migrations are safe to run more than once. If one fails, it is rolled back, nothing after it runs, and the log names the file. The most common cause is a database user without permission to create tables: grant it All privileges on the database (cPanel: PostgreSQL Databases → Add user to database).

The setup token

"That token doesn't match the one this server printed." Copy the whole 43-character token again, without spaces or line breaks. If the app has restarted since, and its storage folder is not writable, a new token was printed: use the latest one in the log.

"Your installer session has ended." Reload the page and enter the token again.

I can't find the token. It is printed under Mailnib is not installed yet. each time the app starts while it is not installed, and saved to storage/.install/setup-token. See The setup token.

/install shows "not found". The installation is already complete, or it was set up with pnpm db:seed (as on Vercel). Sign in at /admin/login. To reinstall on purpose, see Resuming and reinstalling.

"APP_KEY is set to a short, repetitive or published value." You kept the placeholder from .env.example, or a key that is too short. Change the line to APP_KEY= (empty) and restart, and the installer generates a strong one.

"Rotation failed: … opens with neither APP_KEY nor APP_KEY_PREVIOUS." APP_KEY_PREVIOUS is not the key your saved credentials were sealed with. Nothing was changed. Fix the value and run pnpm app-key:rotate again; see Security checks and rotating APP_KEY.

"Too many …. Try again in …" on a busy office network or behind a CDN. Every visitor may look like one address. Set TRUSTED_PROXY_HOPS to the number of proxies in front of the app.

SMTP errors in the installer

Message	Fix
"The SMTP server rejected the username or password."	Check both with your provider. Gmail, Outlook and many others need an app password.
"Couldn't connect to the SMTP server."	Check the host and port, and that your host allows outgoing connections on that port.
"The SMTP host name could not be found."	Check the host name for typos.
"The SMTP server didn't answer in time."	Port 465 needs SSL/TLS; port 587 needs STARTTLS. Try the other setting.
"The encrypted connection failed."	The same: match the encryption setting to the port.
"The server refused the sender or the recipient."	Use a from address on a domain your provider has verified.

S3 required on Vercel

The app stops at start-up with:

Persistent S3 storage is required: set STORAGE_DRIVER=s3 and STORAGE_S3_BUCKET (plus your S3 endpoint, region, and credentials) before starting Mailnib.

Vercel's file system does not keep files between requests, so uploads would vanish. Set the STORAGE_* and AWS_* variables as in Install on Vercel, then redeploy. You also see this message on any host if STORAGE_DRIVER=s3 is set without STORAGE_S3_BUCKET.

Uploads missing after a redeploy

Images uploaded before a deploy show as broken, and the editor's email checks say Image file is missing.

The uploads were written to a folder the host throws away on each deploy.

Render: STORAGE_ROOT must be /var/data, the persistent disk. The Blueprint sets this; check it was not changed.
cPanel: keep the storage/ folder when you replace the application files. See Updating to a new version.
Any host: use S3-compatible storage to make uploads independent of the server.

Files lost this way cannot be recovered by the app. Restore storage/ from a backup, or have customers upload the images again.

Gmail clips the email

Gmail shows "[Message clipped] View entire message" and hides the end of the email, usually including the footer and unsubscribe link.

Gmail clips any email whose HTML is over 102 KB. Open the design and check the size meter in the toolbar. Split long emails, set styles in the theme instead of on each block, and link to long text instead of pasting it in. Images do not count toward the size.

A test send is refused

Message	Fix
"Today's test sends are used up"	The plan's daily test sends are used. The count resets at midnight UTC.
"Too many test sends in a few minutes"	Wait the number of minutes shown.
"An address is no longer confirmed"	The address was removed or its confirmation lapsed. Add it again from Settings → Test addresses.
"The mail service did not accept the message"	The platform's SMTP settings are wrong or the provider refused. Check Email (SMTP) settings and the server log.
"Choose at least one address"	Tick an address. Only confirmed ones are listed.
The test "sent" but never arrived	Check spam. If you run the platform, check that `MAIL_TRANSPORT` is not `log`: with `log`, messages go to the server log, not to inboxes.

Frequently asked

Can I use MySQL? No. Tenant isolation depends on PostgreSQL's row-level security. Use a hosted PostgreSQL if your host has only MySQL.

Does it send campaigns? No, and it will not. Customers export their designs to the service they send from. See Welcome.

Do I need Redis, a queue or a worker? No. One Node.js process and one PostgreSQL database.

Customers never get their confirmation email. Set up Email (SMTP) settings and make sure MAIL_TRANSPORT is not log.

How do I close public sign-up? Set REGISTRATION_DISABLED=true and restart. Existing customers still sign in, and you can still create tenants from the console.

Why is the exported HTML full of tables? Because email clients, Outlook above all, render tables reliably and modern layout unreliably. It is correct email markup.

Where are the logs? cPanel: the log file named in Setup Node.js App. Render: the service's Logs. Vercel: the deployment's Logs. Your computer: the terminal.

Asking for help

Include your version (from the changelog), how you installed (cPanel, Render, Vercel or your own server), the output of /api/health, and the exact message you see, including any Reference code. Never send your .env file or passwords.