Troubleshooting

This is the short list of common failures + workarounds. The embedded known-issues catalog covers each one in machine-readable form so unibench known-issues lookup "<your error>" matches automatically — the GUI's error banner also renders the matching workaround inline.

For anything not covered here, the AI agent's Diagnose tab takes the failing service + an optional question and produces a structured response with citations against tool output.

"Postgres initdb: directory exists but is not empty"

The orchestrator's per-project Postgres data dir at <project>/.unibench-data/postgres/ survives across runs by design. This error fires when a previous initdb left a partial state, or when you've bumped the version and the old major's catalog files are still on disk.

unibench start --fresh

If you have data you care about in the existing data dir, copy it out before --fresh wipes everything.

"Port already in use"

Something else owns the port the manifest asked for (or the orchestrator's default). Common culprits: a previous unibench-daemon that didn't clean up cleanly, a system tool, or another project's services from another Unibench daemon (rare — the daemon is single-instance per user).

lsof -iTCP:<port> -sTCP:LISTEN -n -P

Stop the owning process, or change the manifest to port = "auto" so the orchestrator allocates from its free range.

"Ollama: pull model manifest: file does not exist"

The manifest declares an Ollama model that hasn't been pulled to this machine yet. Models are 2–8 GB and aren't shipped with the app.

ollama pull llama3.2          # or whichever model the manifest names

Or remove the model = "..." line from the manifest's [services.ollama] block to start without preloading; you can pull later through the Ollama CLI.

"No secret found for X" / @keychain: reference fails

The manifest carries a @keychain:<name> placeholder but the named secret isn't in macOS Keychain.

For BYOK provider keys:

printf '%s' "<value>" | unibench secret set anthropic    # or openai

For any other named secret, write it directly via Keychain Access under service com.unibench, account unibench-secret-<name>.

"mise not installed on PATH"

The orchestrator's lockfile-driven runtime auto-install (M4) needs mise separately installed. Without it, services fall back to whatever PATH the daemon inherits (usually Homebrew + system binaries).

curl https://mise.run | sh
# or
brew install mise

Then unibench start again. Already-running projects need a stop

  • start cycle to pick up mise.

"Healthcheck did not pass within retry policy"

The orchestrator runs three healthcheck attempts (5s / 15s / 45s) before giving up. A healthcheck timeout usually means:

  • the service is up but isn't responding correctly (port misconfiguration, missing dep, slow first-run init),
  • a transitively-blocked dependency hasn't come up yet,
  • the healthcheck itself is wrong (e.g. tcp against a port the service didn't actually bind).

Diagnostic order:

  1. Open the service's Logs tab. What is it printing?
  2. Check depends_on. A healthy upstream might still be initializing internally (e.g. Postgres returns pg_isready long before it's actually accepting application connections).
  3. Bump healthcheck_retries in the manifest for the service if first-run initialization is just slow.

Daemon won't start / unibench ping hangs

Two common causes:

  • Stale socket at ~/Library/Application Support/unibench/orchestrator.sock. Delete it and retry.
  • Stuck daemon process. Check with ps aux | grep unibench-daemon and kill the PID; the next unibench command will spawn a fresh daemon.

The audit log (unibench audit -n 50) records every project open/close + service health transition, so even after a clean restart you can see what happened on the last run.

Asking for help

When none of the above fits, generate a support bundle:

unibench support-bundle ~/Code/my-project

…which produces a zip with the redacted manifest, per-service logs, the dependency graph, the resolved runtimes, and the recent audit log. Review it before sharing — per decision 2.32 the bundle is generated on disk only, never auto-uploaded.

The bundle's README.txt lists every section. Inline secrets in the manifest are replaced with <redacted>; @keychain: placeholders pass through (they're already non-sensitive).