Troubleshooting

Start with the failed step, then inspect the service state before retrying.

Installer refuses the host

Use --plan and read its prerequisite errors. The supported automatic install needs an empty, dedicated, already mounted ext4/XFS block filesystem on a different device from /. A directory, bind mount or network filesystem does not satisfy that boundary. Existing accounts/files or listeners cause refusal.

The installer does not prepare disks, install OS packages, edit DNS or take over ports. A failed apply retains state for inspection. Do not repeatedly apply or remove service accounts/data to bypass the guard. Existing services need an upgrade runbook.

Browser cannot connect

Check service status and listeners. In automatic HTTPS mode, DNS must resolve to the host and 80/443 must be reachable and unused by other services. TLS-ALPN validation needs port 443 without a terminating proxy. Use proxy mode when you already terminate HTTPS.

Staging ACME certificates are not browser-trusted; production issuance requires --acme-production. A certificate failure never enables HTTP sign-in. In proxy mode, preserve the configured Host and public HTTPS origin. Rewriting Host or posting from a different Origin is rejected.

Sign-in code does not arrive

Confirm that a service admin enrolled the correct email on an enabled account. The generic browser response deliberately does not identify unknown/disabled addresses. Inspect private daemon logs and SMTP configuration for delivery failures; keep credentials out of shared logs and screenshots.

A new code invalidates the prior one. Use it within ten minutes and five guesses. Delivery/guess throttles may require waiting. Use the authenticated CLI to correct enrollment on the existing identity. There is no public recovery bypass.

Git denies a clone or push

Use the exact clone URL, including a nondefault SSH port. Confirm your registered public key matches your client key, account is enabled and membership grants the needed role. A writer also needs an active repository with safe write admission. Revoked fingerprints cannot be re-enrolled.

Display-name edits preserve clone routes; clone-name edits retire the previous named address. Use the current friendly URL or immutable UUID URL. Administrative SSH access does not grant repository access.

An edit is stale or work stays pending

Reload stale forms and review current values before submitting again. For pending/running jobs, inspect the operation record. An HTTP 202 response means accepted, not complete. Check capacity, barriers and active sessions. A failed operation retains evidence; resolve its cause before the explicit recovery path.

Storage is low

Check actual free bytes and inodes, reservations and the configured target volume/quota. Archive and soft delete retain bytes. Do not purge or prune Git objects automatically. Follow Status and storage.

Browsing cannot show a file

Browsing requires the essentials update. Large/binary/non-UTF-8 content, oversized trees and query bounds can require a clone. README images and relative links are intentionally removed. See browsing limits.