Troubleshooting

You see	Cause	Fix
check-config names a variable	The value is missing or malformed.	Fix the line in pds.env and run the check again. The message says what shape it expects.
docker-compose: command not found, or an error about the Compose file’s version	Compose version 1.	Install the Compose plugin and use docker compose, with a space.
The server exits at start and the log says another server holds the lock	A previous container still runs, or the lock file is left from a copy.	docker compose ps; stop what runs. A stale linkjar-pds.lock in a copied directory can be removed when no server runs there.
curl to the server fails with a certificate error on the first request	Caddy fetches the certificate on the first connection, which takes a few seconds.	Try again. If it keeps failing, DNS does not point at the host, or port 80 or 443 is closed.
A handle’s name gets no certificate	The wildcard record is missing, or the handle is not an active account.	Check dig +short anything.pds.example.com, and the /tls-check route in the checks.
The Bluesky app signs in but cannot load settings, and the log shows getPreferences failing	PDS_BSKY_APP_VIEW_URL and PDS_BSKY_APP_VIEW_DID are unset.	Set both, as in the example file, and restart.
Sign-up fails with an invite code error	PDS_INVITE_REQUIRED is on and the code is wrong or used up.	Create a code with the admin API.
Sign-up fails and the log mentions the rotation key	PDS_PLC_ROTATION_KEY_K256_PRIVATE_KEY_HEX is unset.	Generate one as in the install and restart. Without it the server creates no account.
Posts do not appear for people on other servers	The relay has not crawled the host yet, or cannot reach it.	Wait for the first write after a start, then check getHostStatus as in the first account. The firehose must be reachable at wss://pds.example.com.
Password reset mail never arrives	SMTP is not set, or the URL is wrong.	Email. A wrong URL shows in the log of the request.
The firehose subscriber count stays at 0	The relay is not connected.	Same as the posts above. A proxy in front of DNS that drops long WebSockets is a common cause.
verify prints differences after a restore	The backup was taken while the server ran, without the -wal files.	Restore from a cold backup, or copy the -wal and -shm files with the databases.
A second host started on a copy of the directory	Two servers served one set of accounts.	Stop one at once. The relay and the apps saw two histories; the one that keeps running is the truth, and the other’s writes since the copy are lost.

When the table does not have it, the log has it: docker compose logs pds, with LOG_LEVEL=debug for the detail. Open an issue at github.com/linkjar/pds with the lines around the error; they contain no secret.