Troubleshooting — Nixt Server docs

Where to look first

Tool	Tells you
`versealx-server doctor`	What is wrong with DNS, reverse DNS, certificates, the clock and the store, with what to do. See Monitoring.
`journalctl -u versealx-server`	Why the service stopped or refused to start, and what it is doing.
`versealx-server admin get queue`	Mail still waiting, and why.
`versealx-server admin get trace …`	What happened to a message that has left. See Message trace.
`versealx-server check` and `explain`	Whether the configuration is valid, and what it will do.

Run them as the service user with the configuration path: sudo -u versealx versealx-server doctor --config /etc/versealx-server/versealx-server.toml.

The server does not start

check catches mistakes in the file itself; Configuration lists its messages. These come from run, after the file has been read. Each is printed after versealx-server: .

Message	Cause	What to do
`cannot read versealx-server.toml: No such file or directory (os error 2)`	No `--config`, no `VERSEALX_CONFIG`, and no file in the current directory.	Give `--config /etc/versealx-server/versealx-server.toml` after the command.
`refusing to start: refusing to run as root; …`	Run as root.	Run as the `versealx` user, or through the service.
`tls: <path>: <reason>`	A certificate or key file is missing or will not load.	Put the certificate and key at the paths in `[tls]`, readable by `versealx`. Or run `init --self-signed` on a new node.
tls: `[tls] kind = "acme"` needs the serve role: …	ACME without the `serve` role.	Add `serve` to `roles`, or use certificate files.
`keys: bad key material: <path> is readable by others (mode 644); chmod 600 it`	The key file’s permissions are too open.	`sudo chmod 600 <path>`.
`keys: bad key material: <path>: <reason>`	The key file cannot be read, or is not 32 bytes or 64 hexadecimal characters.	Restore the correct key file. Never replace it with a new one on a node that holds mail.
`keys: cannot write <path>: <reason>`	First start could not create the key file.	Make the directory writable by `versealx`.
`keys: cannot make /run/versealx-server: <reason>`	No `[admin] socket`, and the service cannot write under `/run`.	Set `[admin] socket = "/var/lib/versealx-server/admin.sock"`.
`store: <reason>`	The SQLite file cannot be opened, or PostgreSQL cannot be reached.	Check the path and its owner, or the database URL and network.
`blobs: <reason>`	The message directory cannot be opened.	Check the path and its owner.
`blobs: AWS_ACCESS_KEY_ID is not set`	An S3 bucket without credentials.	Set `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` for the service.
`listener <name>: <reason>`	A port could not be bound: something else is using it, or the process may not bind low ports.	Stop the other program, choose another address in `[listeners]`, or run through the service, which has the capability.
node: `${HOSTNAME}` names an environment variable that is not set	`node` refers to a variable that is empty.	Set the variable, or write the name out.
`resolver: <reason>`	`/etc/resolv.conf` cannot be read, or a trust anchor file is wrong.	Fix the resolver configuration or `[dns] trust_anchors`.
`configuration: <reason>`	An `[outbound] trust` file cannot be read or holds no certificate.	Fix the file.

If systemctl start fails with no clear message, run the same command the service runs, as the service user, to see its output:

sudo -u versealx versealx-server run --config /etc/versealx-server/versealx-server.toml

versealx-server admin does not work

Symptom	Cause	What to do
`cannot reach the admin socket at <path>: No such file or directory (os error 2)` then `is the server running, and does this account own it?`	The server is not running, the `admin` role is off, or the command did not find the configuration and used the default socket.	Start the server; give `--config`.
The same with `Permission denied`	You are not the service user.	Run with `sudo -u versealx`.
The usage text, for a command that looks right	`--config` or `--socket` was placed before `admin`, or the method is misspelled.	Write flags after the command: `versealx-server admin --config <file> get tenants`.
`403` `that belongs to another tenant`	A token-based caller asked about another tenant.	Use the local socket, or the right tenant id.
`404` `no such collection`	A typing mistake in the path.	Check the path against the Admin API.
`400` `password` must be text	The password was all digits and was sent as a number.	Use a password with letters or symbols.

Mail sent to you does not arrive

Work through these in order.

Is it in the trace? versealx-server admin get trace tenant=1 address=<recipient> day=<YYYY-MM-DD>. If it is there, its steps say where it went. If it is not, the server never accepted it.
Does DNS send mail here? doctor must show <domain> MX: names this host. If the MX names another host, mail goes there.
Can the sender reach port 25? From a machine outside your network: nc -v mail.example.com 25 should show 220 mail.example.com ESMTP Nixt Server after two seconds. If not, check your firewall and your provider’s inbound filtering.
What did the sending server get? Ask the sender for the bounce they received. Its reply code says why:

Reply the sender got	Cause	What to do
`550 5.1.1 No such user here`	The address does not exist in the domain.	Create the account or an alias.
`554 5.7.1 Relay access denied`	The domain is not on this server.	Add the domain to the tenant.
`550 5.2.1 Mailbox disabled`	The account is disabled or deprovisioned, or the sender may not write to the group.	Set the status back to `active`, or change the group’s restriction.
`452 4.2.2 Mailbox full; try later`	The mailbox is at its ceiling, or the tenant is suspended.	`vsx admin mailbox usage <address>`, then raise the limit or make room; or `patch tenants/<id> suspended=false`. The sender will retry.
`452 4.3.1 The organisation's mail storage is full; try later`	The organisation is at its storage ceiling.	`vsx admin usage storage`, then raise it with `vsx admin org storage` or make room. The sender will retry.
`550 5.7.1 Refused by the sender domain's DMARC policy`	The message failed the sender’s own DMARC `reject` policy.	The sender must fix their SPF or DKIM.
`550 5.7.1 A message has one From header`	The message has more than one `From` header.	The sender must fix their software.
`550 5.7.1 The From header names more than 5 domains`	The `From` header names authors in more than five domains.	The sender must name fewer authors.
`550 5.7.1 attachment refused by policy: …`	A blocked attachment.	Ask the sender to use a link.
`550 5.7.1 message refused: malware detected (…)`	ClamAV found malware.	None.
`550 5.7.1 message scored …; refused as spam`	The score reached 15.	Check the sender’s SPF, DKIM and DMARC.
`451 4.7.1 malware scanner unavailable: …`	clamd is down and `on_unavailable = "tempfail"`.	Start clamd; the sender will retry.
`550 5.6.0 Bare <LF> received; …`	The sending software ends lines incorrectly.	The sender must fix their software.
`554 5.5.0 Speak after the greeting`	The sending software does not wait for the greeting.	The sender must fix their software.
`421 4.7.0 Too many connections from your address`	More than 20 connections at once from one address.	The sender will retry.

Is it in Junk? A score of 5 or more files mail in Junk. The X-Versealx-Filter header shows why.
Is it quarantined? A score of 8 or more, or a milter’s decision, keeps mail in the hidden Quarantine mailbox. The trace’s filtered step shows Quarantine.

Trying a message before it arrives

To see what the server would do with a message, without sending one, run try message on the node:

versealx-server try message --from ceo@examp1e.com --to ada@example.com --ip 203.0.113.9
versealx-server try message --from billing@supplier.example --to ada@example.com --file invoice.eml --json

It runs the same checks port 25 runs, with your organisation’s own lists, rules and classifier:

what the directory says of each recipient;
SPF, DKIM, DMARC and ARC, read from live DNS;
the filter’s score, with each stage’s contribution and why;
the outcome: inbox, Junk, quarantine, refused or asked to try later.

Nothing is stored, delivered, counted or traced, and asking twice gives the same answer. Without --file, a plain test message is used. --ip and --helo say where the message comes from, and --tls says it arrives encrypted.

An organisation’s administrators can do the same for their own people:

On the console, use the Try a message card on the Filter rules page. Paste a whole message, or leave it empty.
From the command line, run versealx-server admin try message --from ceo@examp1e.com --to ada@example.com.
Through the API, use POST /tenants/{tenant}/try/message with from, to and, optionally, ip, helo, tls and message.

Every recipient must be at one of the organisation’s own domains.

Mail you send is refused or delayed

Refused when sending

Reply in the app	Cause	What to do
`530 5.7.0 Must issue a STARTTLS command first`	The app did not start TLS on port 587.	Set the app to STARTTLS on 587, or SSL/TLS on 465.
`535 5.7.8 Authentication credentials invalid`	Wrong password, no password set, a disabled account, or a lockout.	Check the password; wait 15 minutes after repeated failures; ask an administrator to set one.
`550 5.7.1 Not an address you may send as`	The envelope sender is not the account’s.	Send from your own address.
`550 5.7.1 The From header is not an address you may send as`	An address in the `From` header, or the `Sender`, is not one the account may send as.	Send from your own address.
`550 5.7.1 A message has one From header, of at most 100 addresses, and at most one Sender header, of one address`	The app wrote a second `From` or `Sender` header, several addresses in `Sender`, or more than 100 authors.	Write one `From` header.
`550 5.7.1 <domain> is not proved to be this tenant's, …`	The domain’s ownership is not proved, and a recipient is outside.	Publish the ownership token, a DKIM record or the MX; run the verify command.
`550 5.7.1 Message held: attachment refused by policy: …`	A blocked attachment.	Remove it.

Stuck in the queue

versealx-server admin get queue/<id> shows each recipient’s last error.

Last error	Cause	What to do
`451 4.4.1` with a connection error	Outbound port 25 is blocked, or the destination is down.	Test with `nc -v <their MX> 25` from the server. If blocked, send through a relay.
`451 4.4.1 no MX host of <domain> could be reached`	Every host failed.	As above.
`451 4.4.3 DNS failure: …`	Your resolver is not answering.	Check `/etc/resolv.conf` and `doctor`’s resolver check.
`451 4.7.5 DNSSEC validation failed` or `TLSA lookup failed DNSSEC validation`	The destination’s DNSSEC is broken, or something between you and the resolver alters answers.	Usually theirs to fix; the message is retried.
`451 4.7.5 TLS failed: …`	TLS with the destination failed; under DANE or MTA-STS, its certificate did not match.	Usually theirs to fix. For opportunistic TLS only, a tenant can allow a retry without encryption with `outbound.plaintext_retry`.
`451 4.7.4 TLS required but STARTTLS not offered`	The destination’s policy requires TLS it does not offer.	Theirs to fix.
A `4xx` reply from the other server, such as a greylisting or rate message	The destination asked you to slow down or try later.	Retries continue. Lower the destination’s ceilings with `outbound.destination.<domain>.*` if it keeps happening.

The log line address is not public; skipped means the destination resolved to a private address; that host is not tried.

Returned to the sender

Status	Cause
`550 5.1.2 domain does not exist`	A typing mistake in the domain.
`556 5.1.10 domain does not accept mail (null MX)`	The domain accepts no mail.
`550 5.7.30 REQUIRETLS: …`	The sender required TLS the destination cannot guarantee.
`550 5.6.7 next hop does not support SMTPUTF8`	An internationalised message to a server that cannot take it.
`451 4.4.7 delivery time expired; last error: …`	Five days of retries failed. The last error says why.
A `5xx` reply naming your address, reverse DNS or reputation	The destination does not trust your server. See below.

Delivered, but filed as spam elsewhere

Run doctor and fix every BAD and warn for SPF, DKIM, DMARC and reverse DNS.
Check the headers of a message you sent at the other end: you want spf=pass, dkim=pass and dmarc=pass.
A new address with no sending history is often distrusted by the large providers. Sending through an established relay avoids it.

Symptom	Cause	What to do
A certificate warning	A self-signed certificate, or one that does not cover the name the app uses.	Use a certificate from an authority that covers the host name. With Nixt Mail, compare the fingerprint and choose Trust and connect.
`NO [PRIVACYREQUIRED] LOGIN needs TLS; use STARTTLS`	The app uses port 143 without STARTTLS.	Use port 993 with SSL/TLS.
`[AUTHENTICATIONFAILED]` or `535 5.7.8` for a correct password	The account has no password yet, is disabled, or is locked after 10 failures.	Set a password; set the status to `active`; wait 15 minutes.
Automatic setup finds nothing	The domain is not marked verified, the `autoconfig`/`autodiscover` names do not point at the server, or the SRV records are missing.	Mark the domain verified; publish the names and records.
Cannot sign in — `that application did not register the address it asked to be sent back to`	The console’s return address is not registered.	Add it to `oauth.console.redirect_uris`.
`that address and password did not match` on a sign-in page	Wrong address or password.	Check the address and use the account’s password.
`Your organisation does not allow IMAP from this network`, or the same for another protocol or app	The organisation’s access rules refuse it from where the person is.	Check with `vsx admin access test <address> imap <their address>`, which names the rule that decides.

Certificates

Symptom	What to do
`doctor`: `no certificate has been obtained` (ACME)	Check that every name in `[tls] names` resolves to the node, that port 80 is reachable from the internet, and look for `could not obtain a certificate; will try again` in the log for the authority’s reason.
`doctor`: `… day(s) left, which is past the day renewal was due`	Renewals are failing: same checks.
`doctor`: `BAD DANE … none matches the certificate this node serves`	Urgent: senders that validate DANE are refusing your mail. Publish the record `versealx-server dns` prints, or remove the TLSA record.
MTA-STS senders refuse to deliver	Check `doctor`’s MTA-STS line; the certificate must cover `mta-sts.<domain>` and every MX must be in the policy.

Domain ownership stays Pending

Check that the token is published exactly: dig TXT _versealx-verify.example.com must return the verification value from admin get tenants/<id>/domains/<domain>.
Check the name: a control panel that appends the domain may have published _versealx-verify.example.com.example.com.
Run versealx-server admin post tenants/<id>/domains/<domain>/verify to check again now.
Alternatively, publish the domain’s DKIM record, or an MX naming this server; either also proves the domain.