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.

Marketplace 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 at /_/marketplace. 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 verb returns 402 Payment Required

A 402 specifically means the request's tenant isn't licensed for that plugin (tenant_not_licensed) — most often a call to a tenant-priced plugin with no tenant on the request (missing X-Tenant, or a stale/invalid workspace on the session) or a tenant that has no active plan for it.

• Make sure the request carries a valid tenant, and that tenant holds a plan for the plugin. Manage plans on the plugin's page in the Marketplace / your account.
• A valid-but-just-renewed license rotates in over the 60-second heartbeat — give it a moment. See Licensing & seats.

Note a seat/role denial for an app user (over the seat cap, or lacking the required plugin role) is a 403, not a 402.

A plugin installed but never runs (dormant)

Symptom: the plugin installed, but its verbs 404 / its UI is missing.

An unpaid, expired, or revoked plugin installs dormant — its encrypted bundle is never decrypted or loaded, so it has zero behavior. Bind a valid license (buy or renew) and it recovers to active automatically on the next heartbeat; no reinstall needed. 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

If a mailer is configured, use the self-service reset on the running server: the sign-in screen's "forgot password" (POST /api/_admin/forgot-password) emails a single-use reset link. Otherwise reset it from the CLI — which needs the server stopped (it takes the vault lock):

# stop the server first
./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?

For a core self-update, rollback is mostly automatic: the supervisor keeps the previous binary and rolls back on its own if the new one fails to become ready, so a failed upgrade self-recovers. If you need to revert a successful but unwanted upgrade, use the Settings → System update screen's rollback, or reinstall the prior build.

Restoring a snapshot is a separate, data-only operation — it rewinds the Vault but leaves the current binary in place (so it won't undo a core version change on its own):

# server stopped
./railbase backup --restore /backups/pre-update.vault

Always snapshot before a plugin purge (it permanently deletes that plugin's collections). See Updating and Backups & restore.