Skip to content
Open vault
Documentation

Troubleshooting

Overview

Start with the visible symptom and the time it occurred. Keep the error text, and check whether the node was recently restarted or updated.

After any restart, open /admin, Sign in, and choose Unlock Node before trying a Safe again. Many "Safe unavailable" problems are simply a locked node. See Restarts and Unlocking.

If you ask for help, share the operation you attempted, the visible error, your browser version and the time of failure. Keep PINs, codes, private keys, Safe contents and raw logs private.

Quick reference

What you see What to check next
Docker or Podman is required, or Docker cannot connect Check that Docker Engine is installed and running and that sudo docker info succeeds.
Docker cannot pull the image Check the server's internet connection, the registry error, and the exact image reference copied from the release notes.
host port 80/443 is already in use Another service is using the web ports. Use a separate host or resolve the port conflict before rerunning the launcher.
The admin page will not open or HTTPS fails Check the hostname's DNS records, provider firewall, server firewall and router forwarding if applicable. Read the container logs for the actual certificate or startup error.
The Safe page is unavailable after a restart Open /admin, sign in, and choose Unlock Node.
The setup code is missing Read the original startup log with sudo docker logs unolock-node. It is usable only until its original expiry.
The setup code has expired or cannot be recovered See First-time admin code was lost. Restarting does not issue a new code. Preserve the data volume.
Upgrade unexpectedly asks you to register an administrator Stop and check that you used the original data volume and hostname. See Upgrading Your Node.

Incident triage

Symptom First action Do not do
Container stopped Capture status and recent logs, then start once Repeatedly restart without preserving evidence
Node locked Sign in, then explicitly Unlock Node Assume a running container serves Safe traffic
Health failure Capture the named failed check and the matching bounded logs Copy the whole data volume into a ticket
Storage nearly full Stop new activity and identify database, archive, staging and engine usage Delete database sidecars or archive objects by hand
Client stale or unsigned Use Clients to inspect rebuild and signing status Bypass signed-manifest validation
Bootstrap code unavailable Follow First-time admin code was lost Restart expecting a new code
Suspected compromise Fence the node, preserve logs and immutable release identifiers, and use a clean recovery host Reuse potentially exposed admin, TLS or recovery secrets

Collect more detail

To record which image is installed:

sudo docker inspect unolock-node --format '{{.Image}}'

To check status and read recent logs:

sudo docker ps -a --filter name=unolock-node
sudo docker logs --since 10m --tail 200 unolock-node

For a problem that needs deeper investigation, keep the browser console and network error, the HTTP status, the matching sanitized server event and the time of the request. Hosted-app problems may also need the browser bundle name, asset hash and service-worker state. Do not infer the cause from a generic browser error alone.

Warning

Logs can contain private setup codes and operational information. Do not post raw logs publicly.

Node does not start

  1. Check the container state and recent logs:

    sudo docker ps -a --filter name=unolock-node
sudo docker logs --since 30m --tail 1000 unolock-node

  2. Check persistent-volume ownership, the SQLCipher path, the archive path, the TPM device and tools (if you use TPM key protection), TLS files, the configured domain, and ports 80 and 443.

For source or system-service installations, also run unolock-node status and unolock-node doctor with the installation's explicit config path. The container image can run doctor as a stopped-node maintenance command, but it must receive the same volume, environment overrides, certificate paths and TPM access as the deployed container.

A restored database with cluster history but no matching signed host authority fails startup with CLUSTER_RECOVERY_ISOLATED. See Restoring a clustered backup.

First-time admin code was lost

The one-time admin setup code is printed once and expires after 30 minutes. Restarting an unconfigured node does not issue or print a replacement. Decide which case applies.

The code is still active

Recover the original startup block from your protected logs and immediately complete Register admin:

sudo docker logs unolock-node

The code expired but you know it

Rotate it offline. This records the exact image used by the container, stops the node, creates two private files, and uses the current code to authenticate rewrapping of the protected node secrets:

UNOLOCK_ADMIN_IMAGE="$(sudo docker inspect unolock-node --format '{{.Image}}')"
export UNOLOCK_ADMIN_IMAGE
export UNOLOCK_ROTATION_DIR="$(mktemp -d)"
chmod 0700 "$UNOLOCK_ROTATION_DIR"
read -r -s -p 'Current bootstrap code: ' UNOLOCK_CURRENT_BOOTSTRAP_CODE
printf '\n'
umask 077
printf '%s\n' "$UNOLOCK_CURRENT_BOOTSTRAP_CODE" > "$UNOLOCK_ROTATION_DIR/current-code"
unset UNOLOCK_CURRENT_BOOTSTRAP_CODE
openssl rand -base64 32 | tr '+/' '-_' | tr -d '=\n' > "$UNOLOCK_ROTATION_DIR/new-code"
sudo docker stop unolock-node
sudo docker run --rm \
  --entrypoint unolock-node \
  -v unolock-node-data:/data \
  -v "$UNOLOCK_ROTATION_DIR:/codes:ro" \
  "$UNOLOCK_ADMIN_IMAGE" \
  admin:bootstrap:rotate \
  --config /data/unolock-node/config.json \
  --current-code-file /codes/current-code \
  --new-code-file /codes/new-code
sudo docker start unolock-node
rm -f "$UNOLOCK_ROTATION_DIR/current-code" "$UNOLOCK_ROTATION_DIR/new-code"
rmdir "$UNOLOCK_ROTATION_DIR"
unset UNOLOCK_ROTATION_DIR

Use the replacement code displayed by the command.

  • If any command fails, leave the node stopped. Remove the two private files only after recording the failure and deciding whether the same rotation must be resumed.
  • Use your actual container and volume names if they differ from the defaults.
  • An admin-unlock-tpm deployment must give the maintenance container the same TPM device access as the node.

The original code is unavailable

The protected bootstrap wrapper cannot be authenticated, and the CLI intentionally cannot rotate it.

  • If the node contains data: stop, preserve the volume and seek a recovery review. Do not edit the config or verifier store.

  • If the node genuinely holds no data: erase the volume and initialize a new node identity:

    sudo docker stop unolock-node
sudo docker rm unolock-node
sudo docker volume rm unolock-node-data

    Then create the node again as described in Installing Your Node.

An Administrator was already registered

Do not use bootstrap recovery. Choose Sign in with an admin key and use a registered admin key and PIN.

Hosted client is stale

  1. Confirm the served hashed main bundle and ngsw.json.
  2. In the admin console, open Clients and use the offered rebuild and signing action.
  3. Inspect the service-worker update state.

A valid update must be offered to the user. It must not activate silently.

Federation message is slow

Separate the possible delays: sender queue, lookup, Tor connection, receiver custody, asynchronous destination processing and client refresh. A generic custody response does not prove Safe delivery. Check durable queue state and count-only worker logs without exposing address hashes. See Federation.

Remote Space is slow or stale

Space-list refresh is synchronous but bounded. A failed authority refresh makes the Space stale and read-only. Immutable files with a verified complete local cache may still read. Avoid repeatedly issuing overlapping refreshes. Inspect coalescing, the deadline and the peer operation that timed out. See Shared Spaces Across Nodes.

Video or range read fails

Verify that:

  • the response status is 206 for a range;
  • Content-Range, Content-Length and Accept-Ranges agree;
  • the ETag stays stable;
  • the requested clear range maps to complete 10 MiB encrypted parts;
  • your proxy does not compress archive routes;
  • temporary transfer URLs can be renewed and retried.

Upload appears complete but fails

Check the multipart session identity, the expected encrypted length, part checksums, completion idempotency, the mutable precondition and the publication state. A progress bar at 99 percent is not proof that the final integrity and commit step succeeded.

Failover and DNS problems

For DNS, certificate and passkey problems after moving to a standby, see Troubleshooting failover.

FAQs

Why can't I open my Safe after the server rebooted?

The node starts locked. Open /admin, sign in, and choose Unlock Node.

Will restarting the node give me a new admin setup code?

No. The code is printed once and expires after 30 minutes. Use the recovery steps in First-time admin code was lost.

Can I turn on debug logging?

Set UNOLOCK_DEBUG=true only in a controlled development environment, and review the debug output before sharing it.

Can I delete database or archive files to free space?

No. Do not delete database sidecars or archive objects by hand. Stop new activity and identify what is using the space.

What should I never include in a support request?

PINs, setup or registration codes, private keys, Safe contents, raw logs, Safe identifiers, Receive Addresses, filenames and onion addresses.

Back to Self-Hosted Overview