Troubleshooting

RomM won't start

• Container crashes immediately → check docker logs romm. If it's invalid host in "tcp://..." you're on Kubernetes, see Kubernetes Troubleshooting.
• Database connection errors → verify DB_HOST/DB_PASSWD match your DB container, and that the DB has finished initialising (first run takes longer than you'd think).
• "Page not found" on first load → wait, because initial migrations and resource seeding take a minute.

Login issues

• Getting 403s → Authentication Troubleshooting
• OIDC redirect fails → Authentication Troubleshooting → OIDC
• Forgot the admin password → reset via DB or a fresh admin invite from another admin account.

Scanning problems

• Scan ends immediately, no platforms found → Scanning Troubleshooting
• Platform not detected → check folder slug matches Supported Platforms or add a system.platforms binding in config.yml.
• Scan times out → Scanning Troubleshooting

In-browser play

• EmulatorJS won't load/404 → In-Browser Play Troubleshooting (on the slim image, cores come from a CDN at runtime, so a 404 usually means outbound networks are blocked).
• Netplay doesn't connect → Netplay Troubleshooting, almost always NAT or missing ICE servers

Platform-specific

• Synology Troubleshooting: permission errors, DSM gotchas
• Kubernetes Troubleshooting: the enableServiceLinks fix and related

Still stuck?

• GitHub issues: search first, then open if you've got a reproducible bug.
• Discord: #help channel, staffed by community + maintainers