Troubleshooting

API fails before listening

Check that DATABASE_URL is set, PostgreSQL is reachable from the process/container, and migrations have been applied. JWT secrets must contain at least 32 bytes; the checked-in Compose secret is shorter and must be replaced. Check RabbitMQ credentials and hostnames: Compose services use postgres/rabbitmq, while a process on the host normally uses localhost.

Redis configuration does not currently make Redis a mandatory startup dependency. Review startup logs instead of assuming every Compose service caused the failure. Configuration is loaded from the working directory; starting the binary elsewhere changes which .env file it reads.

A documented request returns 501

This is expected for the documentation-first contracts. Invalid JSON/schema inputs still produce 400/422, but valid requests invoke unimplemented use cases. OpenAPI success examples describe intended responses. Review the service's implementation-status section before investigating persistence or permissions that do not exist yet.

Verification or recovery email never arrives

The current email adapter prints one JSON record to the API console. Inspect development logs for the temporary token and follow the identity guide. It does not send SMTP email. Generic request acknowledgements intentionally do not reveal whether an account exists or delivery failed.

Docs build fails

Follow the local setup and reference generation commands before invoking npm scripts; site navigation requires generated package metadata. Check Go 1.27, workspace paths, the pinned generator, and npm dependencies. A module with no Go packages is reported and skipped in the reference. Broken Markdown links, missing imported files, and invalid JSON fixtures should be corrected rather than ignored globally.

For stale Go pages during a docs development session, rerun GOMARKDOC="$PWD/bin/gomarkdoc" go run ./scripts/docgen/main.go. For /docs/ assets or deep links failing only under Caddy, rebuild the docs image and verify both VitePress's /docs/ base and the Caddy prefix handler.

Where to look next

See configuration, database commands, identity logs and request traces, and the generated Go reference.