When it breaks
Last updated
Most failures on a self-hosted Weald relay come from DNS, port 80, or a database or bucket the relay cannot reach. The rest are an expired bootstrap invite or a client refusing a plaintext connection. Start with the readiness endpoint, which names the failed dependency in words instead of printing a stack trace.
The relay will not start
Check /readyz on the private listener first. It reports Postgres and object storage reachability separately, so a failure names which one.
- Postgres unreachable is usually a connection string naming a host the container cannot resolve. On a first boot the database may also not have finished starting.
- Object storage unreachable on the compose path is the storage container failing its own start. On a bare binary it is a bucket name, a region or a credential.
No certificate
The bundle needs port 80 reachable to complete a challenge. With port 80 closed, the relay answers on no port at all. The failure is reported as a certificate issuance failure instead of an obscure ACME error.
Two other causes follow, the more frequent first. The DNS record points at an address the host does not have, or the hostname in the environment file does not match the name in DNS.
The client will not connect
| The app reports | Cause |
|---|---|
| Refused a plaintext connection | The relay is not serving TLS, or a proxy in front of it is not |
| Hostname does not resolve | DNS, or a private network the client is not on |
| Protocol version unsupported | The relay and the app are too far apart. Upgrade the older one |
| Not in the access set | The device was revoked, or was never enrolled in this workspace |
The client refuses a relay reached over plaintext and never downgrades. The app tells you what happened and does not connect.
The bootstrap invite expired
The enrollment URL is single use and lasts twenty-four hours. While the workspace still has no trust root, the relay can reissue one. Once a first device has enrolled, it refuses permanently and no support path gets around that.
If a workspace has a trust root and nobody can reach it, use the recovery phrase. If the phrase is also gone, the workspace is gone.
Storage is growing and will not stop
Storage falls when a workspace compacts, which is a control in the Mac app. A relay cannot compact on its own. Compaction decides which history to drop, and the relay cannot read history.
A workspace whose admin devices stay offline accumulates uncompacted history, and nothing on the server side fixes that. If storage is climbing with no matching activity, check that an admin device has been online recently.
A member sees a warning nobody else sees
Two warnings cannot be muted. Stop for either one.
- A roster change the member did not perform. Somebody was added or removed, and the client is saying so.
- A split view or transparency warning. Two clients disagree about the history of a group, or one has gone silent when it should have spoken.
Neither belongs in a bug report. Compare safety numbers on two devices and read the transparency log.
What support cannot do
Support cannot read a workspace, list its members, or recover a lost recovery phrase. The client's diagnostic bundle carries versions, sync state, connection history and error logs. Content is excluded, and the exclusion is visible before the bundle is sent.
Support covers what to send and where to send it.