Troubleshooting
This ReputeCast troubleshooting page lists what goes wrong most often on a self-hosted instance, why, and how to fix it. Each entry starts with what you see.
Before you begin
Section titled “Before you begin”-
Read the app’s logs. With Docker Compose:
docker compose logs app --since 1h. With the binary under systemd:journalctl -u reputecast --since "1 hour ago". -
Check the process and the database:
curl -s http://localhost:8080/readyzanswersreadywhen ReputeCast can reach PostgreSQL (health checks, metrics and logs). -
Check the schema:
docker compose exec app /usr/local/bin/reputecast migrate status(orreputecast migrate status) lists any migration aspending. -
For more detail, restart with
REPUTECAST_LOG__LEVEL=debug, and set it back afterwards.
Install and start
Section titled “Install and start”The temporary password isn’t in the logs
Section titled “The temporary password isn’t in the logs”The first Owner and its temporary password are created only on the first start against an empty database. Run:
docker compose logs app | grep -A4 "ReputeCast is installed"- Nothing found, and the database volume existed before: users already exist, so nothing was created. Use the account you made then, or set a new password for it from the server (below).
- Nothing found, and the container was recreated:
docker compose logsshows only the current container’s logs. Set a new password from the server. - You don’t know the Owner’s email: without
REPUTECAST_ADMIN_EMAIL, the shipped compose file usesadmin@example.com.
To set a password from the server:
docker compose exec app /usr/local/bin/reputecast user reset-password --email admin@example.com --password 'a long passphrase here'See recover access from the command line.
The app container keeps restarting
Section titled “The app container keeps restarting”Read the last lines of docker compose logs app. The start stops with Error: …:
Error: previous secret key: key must be 32 bytes, got 0:REPUTECAST_SECRETS__PREVIOUS_KEYSis set but empty. Remove the variable.Error: secret key: key must be 32 bytes, got …orkey must be base64-encoded: the key inREPUTECAST_SECRETS__KEYor the key file is not a base64 32-byte key. Use the valuereputecast secrets generate-keyprinted, unchanged.Error: owner email: … (pass --email or set REPUTECAST_ADMIN_EMAIL): the database is empty and the first Owner’s email is missing or not a valid address.Error: migrate: …: a migration failed. Restore the backup taken before the upgrade and report the error with the version (upgrade ReputeCast).
The logs warn about pending migrations
Section titled “The logs warn about pending migrations”The binary is newer than the database schema and the process was started without --auto-migrate. Run
reputecast migrate up once with the server’s environment, then restart every process. The Docker image migrates at
start by itself.
/readyz answers 503 database unavailable
Section titled “/readyz answers 503 database unavailable”ReputeCast can’t reach PostgreSQL within 2 seconds. Check that the database runs, that REPUTECAST_DATABASE__URL points
at it, and that database.max_conns per process times the number of processes stays under PostgreSQL’s
max_connections (PostgreSQL).
Sign-in
Section titled “Sign-in”Signing in over http:// sends you back to the sign-in page
Section titled “Signing in over http:// sends you back to the sign-in page”Outside development, the session cookie is marked Secure, and browsers don’t keep Secure cookies set by a plain
http:// site, except on localhost
(MDN: Set-Cookie, checked October
2026). Put ReputeCast behind TLS and set http.public_url to the https:// address
(reverse proxy and TLS). For a short test on a private network only, you can set
REPUTECAST_AUTH__COOKIE_SECURE=false.
“Sign-in is locked after too many attempts”
Section titled ““Sign-in is locked after too many attempts””Too many wrong passwords for that email. Lift the lock in
Instance admin, then Users, set a new password through a reset link, or wait for the
lock to end (15 minutes by default). reputecast user unlock doesn’t lift this lock in the current version. See
clear a sign-in lockout.
Authenticator codes fail with secrets: cannot decrypt value
Section titled “Authenticator codes fail with secrets: cannot decrypt value”The secret key doesn’t match the database, usually after a restore without the key or after the key file was lost. Put the original key back. If it is gone, see back up and restore: people sign in with a recovery code or passkey, and an admin resets their authenticator.
Password reset emails never arrive
Section titled “Password reset emails never arrive”Reset emails go out on the System stream. Until a sending provider serves it, the app shows the command to run instead:
reputecast user reset-password --email <address> prints the link on the server.
Sending providers and webhooks
Section titled “Sending providers and webhooks”Provider webhooks never arrive
Section titled “Provider webhooks never arrive”Delivery events stay empty, and a sending provider shows “Degraded · webhooks silent” in
Sending providers. Providers post events to <public URL>/hooks/…, so:
- The public URL must be reachable from the internet. Run Check in
Instance admin, then Instance & updates: the reachability line must pass. A URL like
http://localhost:8080can’t receive webhooks. - Your reverse proxy must forward
/hooks/paths unchanged to ReputeCast. - If you split roles, at least one process must run the
ingestrole behind that address (scale with web, ingest and worker roles).
After a public URL change, the providers that support it get the new webhook address automatically; the page lists the others, where you paste it yourself. See provider health and outages.
Requests to private addresses are refused
Section titled “Requests to private addresses are refused”ReputeCast refuses outbound requests to private and loopback addresses, for example
address not allowed: 10.0.0.5 is a private or loopback address. For a Postal server, an SMTP server or another
service on your own network, set providers.allow_private_networks: true; for webhook endpoints, n8n and the audit
stream, set webhooks.allow_private_networks: true. Link-local and cloud metadata addresses stay blocked. See
security and hardening.
Live monitor never updates
Section titled “Live monitor never updates”The live monitor of a running send stays at its first numbers until you reload. It reads a server-sent event stream at
/api/v1/workspaces/<workspace>/campaigns/<campaign>/live/stream, which sends a heartbeat every 15 seconds. A proxy
that buffers responses holds the events back. Turn buffering off for that path, as shown in
reverse proxy and TLS.
SQL segments are turned off
Section titled “SQL segments are turned off”Building a SQL segment answers SQL segments are turned off on this database. The PostgreSQL role
reputecast_segments is missing, or the app’s database user isn’t a member of it, typically on managed PostgreSQL
where the user can’t create roles. Follow the SQL segments steps: on a database
that was migrated before the role existed, reputecast migrate up alone doesn’t turn them on.
Blocklist checks fail
Section titled “Blocklist checks fail”Blocklist results for Spamhaus or URIBL report an error such as Spamhaus answered 127.255.255.254 (use your own resolver, not a public one) or the list refused queries from this resolver. These lists refuse queries that come
through public resolvers (1.1.1.1, 8.8.8.8). Point dns.servers at your own recursive resolver, for example
REPUTECAST_DNS__SERVERS=10.0.0.53. See check and fix blocklist listings.
Links in sent emails stop working
Section titled “Links in sent emails stop working”Unsubscribe, preference and tracking links in emails sent earlier lead to an error. The links are signed with a key derived from the secret key, so they break when the key changes (a rotation, or a restore without the original key). New emails work. Restore the original key if you still have it (security and hardening).