# Troubleshooting

> Fixes for the issues operators hit most often.

_Updated: 2026-06-08_

A checklist for the problems that come up most. If none of these fit, reach out
via [Support](../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:

```bash
export RAILBASE_VAULT_PASSWORD_FILE=/run/secrets/railbase-vault
```

See [Security](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:

```bash
./railbase serve
```

Then open **Marketplace** in your admin (or `/_pm`). See
[Installing plugins](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](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](../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](/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](licensing-and-seats).

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

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

```bash
RAILBASE_TRUSTED_PROXIES=127.0.0.1/32   # your proxy's CIDR
```

and forward `X-Forwarded-For`. See [Deployment](deployment).

## I forgot the admin password

Reset it from the CLI on the server:

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

## "Address already in use"

Another process holds `:8095`. Pick a different port:

```bash
./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](backups-and-restore).

## How do I roll back a bad update?

Restore the snapshot you took beforehand:

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

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