Harbor

When something breaks

Troubleshoot upgrades, database recovery, locked storage, failed scans, and email connections.

On this page

An upgrade went wrong#

Rolling back is restoring, because migrations only run forward. An older release may not work with an upgraded database schema. harbor upgrade takes a backup immediately before it pulls, and that is the one you want.

harbor config                  # set HARBOR_IMAGE_TAG back to the release you were on
harbor start                   # bring that version up

If the older code cannot read the newer schema, harbor logs api will say so. Then restore the pre-upgrade snapshot as in Restore from a backup, choosing it by timestamp from restic snapshots.

Only the database is gone#

Use this procedure only when you intend to replace the database with the saved dump. Confirm that /data/dumps/harbor.dump exists and is the backup you want. Follow Restore from a backup for the deployment directory and dc alias.

dc stop api web worker mailfetch suggester backup
dc exec postgres psql -U harbor -c 'DROP DATABASE harbor' -c 'CREATE DATABASE harbor' postgres
dc run --rm backup pg_restore --no-owner --exit-on-error \
  --dbname=postgres://harbor:harbor@postgres:5432/harbor /data/dumps/harbor.dump
dc up -d

Check the timestamp of /data/dumps/harbor.dump; a failed backup may leave an older dump. For an older one, restore just that file from the snapshot you want first.

The vault will not start after a reboot#

Check whether the data volume is still locked. harbor unlock, type the passphrase, and the containers start on their own. While the volume is locked the mount point is write-protected, so nothing has written to the wrong disk in the meantime.

A scan failed#

The Inbox card says so and offers Retry. The original is stored before text extraction. A failed scan can leave its contents unsearchable until processing succeeds. harbor logs worker shows every scan with its engine, pages and time.

A mail connection stopped#

Open Settings → Email and read the connection error. Check the mailbox credentials and provider availability. Update revoked credentials and reconnect; for a rate limit, follow the provider’s retry guidance.