macOS Troubleshooting

Start with the quick checks, then jump to the symptom. Problems that are the same on every platform (sync, S3 vaults, previews, shares) are in General Troubleshooting.

Quick Checks

1vh status2for d in postgres server web caddy; do3  printf '%-10s ' "$d"; sudo launchctl print "system/sh.vaulthalla.$d" 2>/dev/null | awk '$1=="state" {print $3; exit}' || echo "not loaded"4done5sudo tail -n 40 /Library/Logs/Vaulthalla/server.log6sudo tail -n 40 /Library/Logs/Vaulthalla/vaulthalla.log7sudo /usr/local/lib/vaulthalla/vaulthalla-provision

The last command changes nothing: on a healthy install it ends with 0 change(s) to make. Anything it lists is something missing or out of place, and --apply repairs it.

macOS Won't Open The Package

Opened from Finder, the unsigned package is blocked the first time. Open System Settings → Privacy & Security and choose Open Anyway next to the message about the package, then open it again. Installing with sudo installer -pkg … -target / or the Homebrew cask avoids the prompt. See Install On macOS.

The Installation Failed

Installer reports "The installation failed" when the package's post-install provisioning stops. It stops rather than guesses whenever something on the Mac isn't what it would have created itself. The reason is in the installer log:

1grep -E 'postinstall|preinstall' /var/log/install.log | tail -40

Message	Meaning and fix
`an existing _vaulthalla account doesn't match what this script creates (…)`	An account with that name exists with different settings (listed in the parentheses). Inspect it with `dscl . -read /Users/_vaulthalla`. Vaulthalla never adopts or changes an account it didn't create.
`a user named 'vaulthalla' already exists` / `a group named 'vaulthalla' already exists`	Another account already uses the alias the service needs.
`… exists, owned by … (expected _vaulthalla:_vaulthalla); refusing to take it over`	A directory under `/Library/Application Support/Vaulthalla` belongs to someone else.
`… is a symlink; refusing to use it`	A path the service owns was replaced by a symlink.
`…/postgres/data exists but is not a PostgreSQL cluster`	Leftovers in the database directory. Move them aside.
`the bundled PostgreSQL did not come up`	See The Database Doesn't Start.

After fixing the cause, install the package again; provisioning picks up where it stopped.

vh Says Permission Denied

1vh: permission denied opening /Library/Application Support/Vaulthalla/run/cli.sock.

Your account isn't in the _vaulthalla group. The installing user is enrolled automatically; others are enrolled by an administrator:

1dsmemberutil checkmembership -U "$USER" -G _vaulthalla2sudo dseditgroup -o edit -a "$USER" -t user _vaulthalla3sudo dscacheutil -flushcache

If the socket opens but vh reports user not found: no Vaulthalla user is mapped to Linux UID … (the wording is the same on macOS), the account is enrolled but not mapped to a Vaulthalla user. See CLI Access.

vh Says The Daemon Is Not Running

1vh: the vaulthalla daemon is not running (nothing is listening at …/cli.sock).

1sudo launchctl print system/sh.vaulthalla.server | grep -E 'state|last exit|runs'2sudo tail -n 60 /Library/Logs/Vaulthalla/server.log

A state = spawn scheduled with a growing runs count means the server starts and exits: the reason is at the end of server.log. The most common one is the database (next section). If the daemon isn't loaded at all, start it with sudo launchctl bootstrap system /Library/LaunchDaemons/sh.vaulthalla.server.plist, or run sudo /usr/local/lib/vaulthalla/vaulthalla-provision --apply.

The Database Doesn't Start

1sudo launchctl print system/sh.vaulthalla.postgres | grep -E 'state|last exit'2sudo -u _vaulthalla /usr/local/libexec/vaulthalla/postgresql/bin/pg_isready \3  -h "/Library/Application Support/Vaulthalla/postgres" -p 369714sudo tail -n 60 /Library/Logs/Vaulthalla/postgres.log

Port 36971 in use: another program holds it (sudo lsof -nP -iTCP:36971 -sTCP:LISTEN).
"database files are incompatible" or a damaged cluster: restore from a dump (see Backup And Recovery); never initialize over the data directory.
The server can't authenticate after a restore: the daemon's sealed password no longer matches the role. Set a new password on the role and hand it to the daemon through run/db_password (owned by _vaulthalla, mode 0600); the daemon seals it on its next start.

The server also survives a database restart on its own: its connections reconnect once PostgreSQL is back, and when PostgreSQL starts after it (at boot), launchd retries the server until it can connect.

The Web Console Doesn't Load

1curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:36968/2sudo launchctl print system/sh.vaulthalla.web | grep -E 'state|last exit'3sudo tail -n 40 /Library/Logs/Vaulthalla/web.log

Without HTTPS the console answers only at http://127.0.0.1:36968 on the Mac itself. From other devices, set up Caddy.

HTTPS Through Caddy

1sudo vh setup caddy --status2sudo tail -n 40 /Library/Logs/Vaulthalla/caddy.log

Symptom	Cause and fix
`port 443 is in use by …`	Another program listens on :80 or :443. Stop it, or bind Caddy to one address with `--listen`.
The browser says the certificate isn't trusted (internal name)	The device doesn't trust the Vaulthalla CA yet. See Trust The Vaulthalla CA.
The hostname doesn't resolve	Add a DNS record on your router, or `--hosts-entry` for the Mac itself.
A public certificate never arrives	Without `--dns-cloudflare`, Let's Encrypt must reach the Mac on ports 80/443 at that name. Check `caddy.log`, then try `--dns-cloudflare`. Rehearse with `--acme-staging` to avoid rate limits.
`the generated configuration didn't validate; nothing was changed`	The working configuration is still in place. The lines before the message say why (for example, a malformed Cloudflare token).
`has no Cloudflare DNS module`	The Caddy in use isn't the package's. Source builds use Homebrew's Caddy, which has no DNS providers.

Health Shows Warnings You Didn't Expect

vh status on macOS always shows mount: disabled -> disabled and secrets backend: file (development: no hardware binding). Both are expected for the macOS package: there is no Finder mount, and master keys are protected by permissions and FileVault rather than hardware. They are reported, not hidden, so that health never claims more than the host provides.

Start Over Without Losing Data

Reinstalling the same package repairs program files and provisioning without touching vaults:

1sudo installer -pkg vaulthalla-<version>-arm64.pkg -target /

sudo "/Library/Application Support/Vaulthalla/uninstall.sh" followed by a fresh install also keeps data. Only --purge deletes it.

Collect Information For A Bug Report

1vh version; vh status2sw_vers; uname -m3sudo /usr/local/lib/vaulthalla/vaulthalla-provision4sudo tail -n 200 /Library/Logs/Vaulthalla/server.log /Library/Logs/Vaulthalla/vaulthalla.log5grep -E 'postinstall|preinstall' /var/log/install.log | tail -60

The install acceptance checks that logs never contain the admin or database password; still, check anything you paste for vault or file names you'd rather not share.