Troubleshooting
Find the failed boundary and verify each telemetry type after a fix.
Gateway is not ready
Find the failed Railway service and inspect its startup logs. Bootstrap waits for migrations and workers. Do not run concurrent manual migrations or delete initialization evidence to hide a failure.
Deployment readiness is a startup check, not continuous monitoring. Verify scheduler activity and consumer progress after the system becomes healthy.
No events, logs or traces
- Check the DSN public key and project ID against Client Keys (DSN).
- Confirm the application runs in the same Railway environment and uses the private Gateway listener on port
8081. - Confirm the selected project, environment and time range in each telemetry view.
- Run the matching SDK example and inspect the application's flush result.
- Inspect Relay, Kafka, Sentry consumers and Snuba consumers for failures or lag.
The public interface rejects ingestion. Adding a public proxy to the private listener changes this profile's boundary and is not a troubleshooting step. railway run on a laptop does not provide private network access.
Login fails
Use Web's generated administrator credentials for your own installation. Changing ADMIN_PASSWORD does not reset an existing user. Use the interactive password reset.
The live demo has a separate public account and read-only policy. Its credentials do not work on your installation.
Invitations or password-reset email do not arrive
Mail is disabled by default. Configure SMTP variables on Web and matching references on consumers and tasks. Verify the provider-authorized sender and actual delivery before depending on email.
Older data is missing
Indexed retention and queue retention are different policies. Check the configured retention and Kafka consumer lag. Deleted queue records cannot be recreated by resetting offsets.
If a consumer offset is outside the retained range, record the missing range, take backups and use the earliest surviving data. Verify known receipts and record any loss rather than claiming complete recovery.
Cleanup fails or stops progressing
Inspect /tmp/cleanup-status.json on the tasks service. Alert on a non-null last_error or a missing or old last_completed relative to the configured schedule and bounded run. Resolve storage or relational errors and verify a later successful completion.
Legacy raw objects without expiry metadata remain until an operator can establish their age from authoritative records. Raw expiry is not proof of relational cleanup or ClickHouse TTL.
After a restart or upgrade
Verify a saved error event, structured log and trace, then send fresh data. Check administrator authentication, workers and cleanup. Follow Upgrades for coordinated backup and rollback.
Sources: operations, recovery, template README.