Troubleshooting

A checklist for the problems that come up most. If none of these fit, reach out via Support.

Railbase won't start in production

Symptom: the server exits immediately with a vault-password error.

In production (RAILBASE_PROD=true) a vault password is mandatory — Railbase will not use the development key. Provide one:

export RAILBASE_VAULT_PASSWORD_FILE=/run/secrets/railbase-vault

See Security.

The marketplace / /_pm is a 404

The marketplace is on by default, so a 404 means it was switched off. Make sure RAILBASE_PLUGIN_MANAGER isn't set to 0 (or false), then restart:

./railbase serve

Then open Marketplace in your admin (or /_pm). See Installing plugins.

A plugin won't install or register

Symptom: install fails, or a plugin never comes up.

• Version mismatch. The plugin requires a newer core (min_core). Update the core first (self-update), then retry. See Updating.
• Verification failed. The artifact's signature didn't match the pinned vendor key. This is the safety gate doing its job — retry the install; if it persists, contact Support. Never disable verification.

A plugin returns 402 Payment Required

The license is lapsed, cancelled, or over its seat limit.

• Check the license and renewal date under My licenses & billing in the console or your account.
• If you're over seats, raise the seat count in Manage billing; it reconciles on the next license refresh.
• A valid-but-just-renewed license rotates in over the heartbeat — give it a moment. See Licensing & seats.

Client IPs are wrong (rate limits, audit log show the proxy)

You're behind a reverse proxy without trusting it. Set:

RAILBASE_TRUSTED_PROXIES=127.0.0.1/32   # your proxy's CIDR

and forward X-Forwarded-For. See Deployment.

I forgot the admin password

Reset it from the CLI on the server:

./railbase admin reset-password you@example.com

"Address already in use"

Another process holds :8095. Pick a different port:

./railbase serve --addr :9000

I lost pb_data/.secret

That file is the master key for the vault. Without it the .vault file cannot be decrypted, and there is no recovery path. Restore it from your backups — and going forward, always back up .secret alongside (but separately from) your vault snapshots. See Backups & restore.

How do I roll back a bad update?

Restore the snapshot you took beforehand:

./railbase backup --restore /backups/pre-update.vault

Always snapshot before a core self-update or a plugin purge.