Recover Administrator Access

Available only for:

Self-hosted Bytebase version 3.22.0 and later
Shell access to the host, or kubectl access to the cluster, that runs Bytebase

When nobody can sign in, bytebase recovery restores password sign-in from the command line. It opens an interactive menu with two actions, Enable password sign-in and Reset user password, and changes the metadata database directly, so it works while the console is unreachable. Recovery requires downtime. If any Workspace Admin can still sign in, reset passwords, roles, and 2FA from the console instead.

Recovery actions and limits

Situation	Recovery action
An administrator knows their password, but Disallow signin with email & password is on	Enable password sign-in
A user’s password is unknown, or the user is locked out after too many failed password attempts	Reset user password
Disallow signin with email & password is on and no administrator knows a password, for example because all administrators use SSO	Reset user password for an administrator, then Enable password sign-in in the same session
A user was removed from Members and has no workspace role	Reset user password, then confirm adding the user and select a role

Recovery can’t do the following:

Create or reactivate a user: the target must be an existing, active user. Service accounts and workload identities are rejected.
Change the role of a user who already has one: the command offers a role only when the user has no workspace role, whether direct, through a group, or through allUsers. If no active Workspace Admin is left and every user already has a role, recovery can’t restore administrator access.
Reset two-factor authentication: only another Workspace Admin can reset a user’s 2FA.
Bypass the workspace domain: when Members restriction is on, the user’s email must belong to an allowed workspace domain.

If none of the actions fits, contact us.

Run recovery

Stop every Bytebase server that uses the metadata database before you run recovery, and keep them stopped until the session exits. Running servers cache the settings, users, and roles that recovery changes.

Run bytebase recovery from an interactive terminal, with the same Bytebase version and the same metadata configuration as the stopped server. Recovery doesn’t migrate the metadata schema, so the version must match exactly: never use a floating image tag such as latest.

Docker
Kubernetes
Binary

The commands assume the container is named bytebase. Substitute your own container name. Because the server container is stopped, recovery runs in a one-off container. Keep -it, because recovery only accepts input from a terminal.

Check the version and the image before you stop the server:
docker inspect --format '{{index .Config.Labels "org.opencontainers.image.version"}} {{.Image}}' bytebase
If the version is older than 3.22.0, stop here and upgrade first. Use the printed image ID as <image> in the next steps, so recovery and the restart run the exact image the server ran.
Stop Bytebase:
docker stop bytebase
Back up the metadata: the data directory for embedded PostgreSQL, or the metadata database for external PostgreSQL.
Run recovery with the same flags the server uses to reach its metadata. For embedded PostgreSQL, that is the data volume:
docker run --rm -it --name bytebase-recovery \ --volume <host_data_dir>:/var/opt/bytebase \ <image> recovery
If the server passes --data, mount that path instead and pass the same --data after recovery. For external PostgreSQL, that is PG_URL:
docker run --rm -it --name bytebase-recovery \ -e 'PG_URL=<pg_url>' \ <image> recovery
Add every other flag the server needs to reach PostgreSQL: --network or --add-host, the --volume of a connection-string file or TLS certificate, and the credential variables for IAM authentication. If PG_URL is a file path, mount that file.
After you exit the session, start Bytebase again on the same image. If your docker run command uses a floating tag or --pull always, replace the image name with <image> and drop --pull always, so the restart doesn’t upgrade Bytebase.

The commands work for both the Helm chart and the manifest from Deploy with Kubernetes. Both create a StatefulSet named bytebase, with Pods labeled app=bytebase, that uses external PostgreSQL. Because the server Pods are stopped, recovery runs in a one-off Pod. Keep -it, because recovery only accepts input from a terminal.

Check the version before you scale down:
kubectl -n <namespace> exec bytebase-0 -- bytebase version
If the version is older than 3.22.0, stop here and upgrade first. If the image tag is floating, such as latest, use the printed version as the tag in step 4.
Stop every replica, then repeat the second command until it lists no Pods:
kubectl -n <namespace> scale statefulset bytebase --replicas=0 kubectl -n <namespace> get pods -l app=bytebase
Pause helm upgrade and any GitOps sync, such as Argo CD or Flux, until recovery finishes, because they restore the replica count.
Back up the metadata database, or take a snapshot with your managed PostgreSQL service.

Run recovery in a one-off Pod with the same image and PG_URL as the server. If the StatefulSet sets PG_URL as a literal value, pass the same value:

kubectl -n <namespace> run bytebase-recovery \
  --rm -it --restart=Never \
  --image=<image> \
  --env='PG_URL=<pg_url>' \
  --command -- bytebase recovery

If the menu doesn’t appear, press Enter.

PG_URL uses valueFrom, a file path, or IAM authentication

Create a Pod that gets PG_URL the same way the server does: give it the same env as the Pod template of the StatefulSet, plus any volumes, volumeMounts, and serviceAccountName the template sets. The example reads PG_URL from a Secret:

apiVersion: v1
kind: Pod
metadata:
  name: bytebase-recovery
  namespace: <namespace>
spec:
  restartPolicy: Never
  containers:
    - name: recovery
      image: <image>
      command: ["sleep", "3600"]
      env:
        - name: PG_URL
          valueFrom:
            secretKeyRef:
              name: <secret_name>
              key: <secret_key>

If the experimental escapePassword option of the chart is on, set PG_URL to the full connection string with the password percent-encoded instead.Save the manifest as bytebase-recovery.yaml, then start the Pod, run recovery inside it, and delete it afterward:

kubectl apply -f bytebase-recovery.yaml
kubectl -n <namespace> wait --for=condition=Ready pod/bytebase-recovery --timeout=120s
kubectl -n <namespace> exec -it bytebase-recovery -- bytebase recovery
kubectl -n <namespace> delete pod bytebase-recovery

After you exit the session, restore the replica count:
kubectl -n <namespace> scale statefulset bytebase --replicas=<replicas>
If the image tag is floating, the new Pods pull the newest image, which upgrades Bytebase. Pin the tag to the recorded version first to avoid that.

For a bytebase binary that runs directly on a host, without a container.

Check the version before you stop the server:
bytebase version
If the version is older than 3.22.0, stop here and upgrade first.
Stop the Bytebase server.
Back up the metadata: the data directory for embedded PostgreSQL, or the metadata database for external PostgreSQL.
Run recovery with the same binary, as the same OS user that runs the server. For embedded PostgreSQL, pass the same --data as an absolute path, and the same --port if the server sets one:
bytebase recovery --data <data_dir>
For external PostgreSQL, pass the same PG_URL:
PG_URL='<pg_url>' bytebase recovery
After you exit the session, start the Bytebase server again.

Use the recovery session

The session shows a menu until you enter q, so you can run several actions in a row. The example resets a password:

Select a recovery action:
1. Enable password sign-in
2. Reset user password
q. Exit
> 2
User email (blank to cancel): admin@example.com
Password requirements:
- Minimum length: 8 characters
New password:
Confirm new password:
Resetting user password...
Password updated for user admin@example.com.

Each action applies immediately and changes only what it names: the sign-in setting, one user’s password, or one role. Exiting at the menu leaves nothing half-done.

Enable password sign-in: switches off Disallow signin with email & password. The menu lists it first, but when no administrator knows a password, reset one first.
Reset user password: enforces the workspace password restriction and clears the lockout from failed password attempts. It doesn’t change the user’s 2FA or SSO sign-in.

After recovery

Open Bytebase and sign in with the email and password, then verify the account’s access.
Repair and test the identity provider.
Switch Disallow signin with email & password back on in Settings > General > Account if it was on before the outage.
Review the recovery events in the audit log. Each action records a warning-level event whose method starts with /bytebase.cli.Recovery/.

Troubleshooting

Terminal required

Error: recovery requires terminal input and output

Password entry must stay hidden, so recovery refuses piped or scripted input. In a container, add -it to docker run, kubectl run, or kubectl exec. On a host, run the command from an interactive shell, with ssh -t when you connect over SSH.

Data directory not accessible

Error: failed to open recovery metadata store: unable to access --data directory /srv/bytebase: stat /srv/bytebase: no such file or directory

The --data path doesn’t exist where recovery runs. With a binary, pass the same --data as the server, as an absolute path. With Docker, mount the data volume at that path.

Embedded metadata database not initialized

Error: failed to open recovery metadata store: embedded metadata database is not initialized at "/var/opt/bytebase/pgdata"

This error appears only when PG_URL isn’t set. The data directory exists, but it isn’t the one the server uses. With Docker, the volume isn’t mounted or the host path is wrong. With a binary, --data is missing or wrong. If the server uses external PostgreSQL, pass PG_URL instead.

Embedded metadata database not readable

Error: failed to open recovery metadata store: failed to inspect embedded metadata database: stat /srv/bytebase/pgdata/PG_VERSION: permission denied

Recovery runs as a different OS user than the server. Run it as the user that owns the data directory.

External metadata database not connected

Error: failed to open recovery metadata store: failed to connect to external metadata database: ...

This error appears only when PG_URL is set, and the text after the last colon names the cause. Recovery needs everything the server uses to reach PostgreSQL: the network (--network or --add-host with Docker), a mounted connection-string file when the cause is failed to read database URL from file, TLS files, or IAM credentials.

Unknown command

Error: unknown command "recovery" for "bytebase"

The image or binary is older than 3.22.0. Upgrade to 3.22.0 or later, start the server once so it migrates the metadata, then run recovery with the new version.

No usable workspace administrator

Failed to enable password sign-in: no usable workspace administrator has an active end-user identity with a password credential

Enable password sign-in requires an active Workspace Admin user with a password, so that someone can sign in afterward. Run Reset user password for an administrator, then retry. If no active administrator is left, reset a user who has no workspace role and add that user as Workspace Admin. If every user already has a role, recovery can’t restore administrator access.

AI

Security

General

Recover Administrator Access

Recovery actions and limits

Run recovery

Use the recovery session

After recovery

Troubleshooting

Terminal required

Data directory not accessible

Embedded metadata database not initialized

Embedded metadata database not readable

External metadata database not connected

Unknown command

No usable workspace administrator

​Recovery actions and limits

​Run recovery

​Use the recovery session

​After recovery

​Troubleshooting

​Terminal required

​Data directory not accessible

​Embedded metadata database not initialized

​Embedded metadata database not readable

​External metadata database not connected

​Unknown command

​No usable workspace administrator

Recovery actions and limits

Run recovery

Use the recovery session

After recovery

Troubleshooting

Terminal required

Data directory not accessible

Embedded metadata database not initialized

Embedded metadata database not readable

External metadata database not connected

Unknown command

No usable workspace administrator