Troubleshooting#
Nodehouse refuses to start#
Read the first startup error. In production, confirm a strong SysOp bootstrap
password is present for a fresh database, the HTTP and Telnet ports differ, and
the database directory is writable. The service also creates data/transfers
for staged offline packets at startup, so the application directory must be
writable too. Run npm run verify before retrying.
/healthz is unhealthy#
Check the active database path, volume mount, file ownership and available disk space. Stop repeated restarts until the data path is understood. Restore from a tested backup if SQLite integrity is damaged.
The browser loads but the terminal does not connect#
Verify the reverse proxy forwards WebSocket upgrades and that the browser's origin is allowed. Check the browser console and service log for an origin or upgrade rejection. Test directly against the internal HTTP port to separate proxy and application failures.
Telnet does not connect or renders badly#
Confirm the TCP port is forwarded directly to the Telnet listener, not the HTTP proxy. Use an ANSI-capable Telnet client. Check that no other service owns the port and that the platform exposes TCP networking separately from HTTP.
A caller cannot sign in#
Confirm the username, registration policy and account access level in the SysOp panel. Reset the password only after verifying the caller through a separate channel. Repeated failures may be temporarily rate-limited.
The Control Desk rejects an operator#
| Symptom | Check | Recovery |
|---|---|---|
Sign-in returns Invalid credentials or insufficient access |
The account's access level | The panel needs level 100 or above. Raise the level, or use a SysOp account. |
A signed-in operator gets Insufficient access |
Which tab they used | Accounts, password resets and bulletins need level 200. Level 100 reaches everything else the desk offers, including message removal, the audit trail and the full caller-card list. |
| An operator is signed out unexpectedly | Recent account changes | Changing an account's level, resetting its password or deleting it ends that account's admin sessions. Sign in again. |
| Demoting or deleting a SysOp returns a conflict | How many SysOp accounts exist | The last SysOp cannot be demoted or deleted. Promote a second SysOp first. |
| A password reset is refused | The new password length | Administrative resets require at least 12 characters. |
The ANSI Art Gallery is empty or a piece will not open#
An empty list means the art/gallery directory is missing or holds no matching
files. Confirm it is present in the deployment and that filenames use only
letters, digits, _ or - and end in .ans.
A single piece that reports itself unavailable is being rejected, not lost. The board refuses artwork over 256 KB and artwork wider than 80 columns, and strips escape sequences other than colour selection, so a piece may render with less decoration than in its original editor. Re-export the file at 80 columns and add it again.
An offline packet link fails#
| Symptom | Check | Recovery |
|---|---|---|
| The link is not reachable at all | Whether the caller can open the board's HTTP address | Packet links live on the HTTP listener. Telnet callers still need the web address, which must be published and reachable. |
Transfer expired or already used |
Age and prior use | Links last 15 minutes and work once. Request a new packet. |
| Requesting a packet reports a limit | Recent activity for that caller | Two unused links per format and direction, and six download packets per 15 minutes. Use or wait out the earlier links. |
| An upload is rejected as too large | Packet size | The upload cap is 4 MB. Reply to fewer messages per packet. |
| An upload is rejected as invalid | Archive contents | Encrypted, oversized or malformed archives are refused. Rebuild the reply packet with the offline reader that produced it. |
| An upload reports it was already imported | Whether the packet was sent twice | Identical packet content is imported once per caller. Check whether the replies already appear before resending. |
| An upload is rejected for a conference or parent | The caller's access level and the reply target | Replies must target a conference the caller can reach, and a reply naming a parent must name one in the same conference. Adjust the access level or drop the reply. |
Nothing is committed from a rejected packet, so retrying a corrected packet is safe.
A caller card does not appear in the directory#
Cards are private until the caller opts in, including profiles carried forward from an earlier release. The caller must publish their own card; an operator cannot do it for them. An operator can only hide a card that is visible.
A Front Porch post does not appear#
Posts from callers below level 100 wait for moderation. Approve or remove them from the Control Desk. Posts also disappear on their own once their expiry date passes.
A page or telegram does not arrive#
Pages reach online nodes only, expire after a minute if unanswered, and are refused when the recipient is set to Do Not Disturb or is already in a private chat. Repeated attempts are limited by a short cooldown. A telegram is always delivered as ordinary local E-Mail, whether or not the recipient is online; check the recipient's mailbox before assuming it was lost.
The wrong database opened after an upgrade#
Stop the service immediately. Inspect NODEHOUSE_DB_PATH and the files in the
persistent data directory. Do not copy databases over one another. Point the
service at the intended file, restart once and verify callers and messages.
When sharing diagnostics, remove passwords, admin tokens, packet transfer links, caller data, private messages, filesystem paths and model-provider keys.