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.

Unless RAILBASE_DEV=true, a vault password is mandatory — Railbase only falls back to the development key in dev mode, and otherwise refuses to boot without one. 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 the vault password

The vault password is what decrypts the .vault file: the master key is derived from it (Argon2id), and without that material the file cannot be opened. There is no recovery path. In production the password comes from RAILBASE_VAULT_PASSWORD_FILE (or RAILBASE_VAULT_PASSWORD); the first-run wizard can also persist it to pb_data/.vault_password. Keep that secret backed up — separately from your vault snapshots, since a snapshot you can't decrypt is worthless. See Security and Backups & restore.

I lost pb_data/.secret

.secret is not the vault key — it's a separate 32-byte master secret that seeds session-token and cookie HMAC, the audit-log hash-chain seal, and the field-level encryption KEK. It is created at railbase init and is not rotatable without re-deriving everything that depends on it, so losing it has no recovery path: live sessions stop verifying and sealed/encrypted values become unreadable. 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.