Troubleshooting

Troubleshooting

Common problems and their fixes. If a symptom isn't listed here, check the live log viewer under Settings → Diagnostics first — most failures log a precise reason.

Adaptive routing selected no model

Run holaryn routing simulate "<representative prompt>" and inspect every candidate's rejection
reasons. Capability, local-only/local-to-cloud, provider pin, allow/deny, availability/rate,
context/output, reasoning, maximum-cost, and maximum-latency rules are hard gates. Unknown cost or
latency fails closed only when that ceiling is configured. An ineligible manual pin is intentionally
not bypassed. See Adaptive model routing for setup, reset, and static rollback.

Provider recovery did not retry or fall back

Open Settings → Providers & Models → Provider recovery and check:

• recovery is enabled and the failure category's action permits retry or fallback;
• an explicit chain or automatic candidate is eligible under capabilities, context/output,
  local/cloud, provider pin, allow/deny, maximum cost, and maximum latency;
• the selected model was not manually pinned (pinned fallback defaults off);
• no response text/tool-call fragment was visible and the transcript does not end after a
  consequential or unknown tool result;
• the candidate's circuit is not open.

Authentication, invalid request, safety refusal, cancellation, and unknown failures stop by
default. Partial responses are retained as incomplete and require a new instruction. Use
holaryn routing health for content-free circuit/attempt diagnostics, and reset with
holaryn routing reset-circuits --yes only after understanding the outage. See
Provider recovery.

"No runnable provider" / no provider configured

The agent does not silently choose a built-in vendor or model—an unconfigured agent tells you
exactly this. Add a provider connection and a model, and set it as the default, in Settings →
Providers & Models (Anthropic, OpenAI, Gemini, or any
OpenAI-compatible/local endpoint such as Ollama). Optional provider recovery cannot replace a
missing primary configuration.

"Credential pool is unavailable" / throttled

Open Settings → Providers & Models → Credential pools, expand the affected pool, and inspect each
alias's drain/auth/circuit state, active leases, configured quota, provider remaining counters, and
recent selection reason. A missing retry time usually means a local policy gate (allowlist, revoked
member, validity window, or configured quota); a timestamp points to a provider rate reset or circuit
cooldown.

Use Preview selection with the intended scope before changing policy. Drain or revoke only when
you intend to stop new work; revocation with cancellation discards late results. If a host crashed,
active leases recover from credential-pools.sqlite3 and expire conservatively at their lease
deadline. For corrupt non-secret runtime state, stop the host, preserve a diagnostic copy, then
restore a known-good state backup or remove only that database to rebuild health/fairness history.
Pool configuration remains in providers.json. See the
credential-pool recovery contract.

If the agent runs as a Windows service, remember the service does not see your per-user environment: set API keys machine-wide (or for the service account), not per-user.

Prompt cache never hits / says bypassed or unknown

Open the model's Cache diagnostics (metadata only) in Settings. minimum_size means the stable
prefix is too small; retention_forbidden means consent is absent; instruction/tool/profile/policy
reasons identify the boundary that changed. unknown means the provider omitted decisive usage
categories—Holaryn does not guess from latency. See Prompt caching for supported
TTLs, isolation, corruption recovery, and provider documentation.

Port 8765 busy or "host is already running"

Only one host can own a state directory at a time; a second holaryn serve against the same state dir refuses with a “host is already running for state dir” diagnostic. That is by design — attach to the running host instead:

• The desktop app attaches to an already-running host (such as the service) rather than starting a second one.
• The CLI drives the running host too: holaryn status, holaryn question, holaryn steer, and friends discover it automatically.

If a different program occupies port 8765, start the host on another port with holaryn serve --port <n>. If you genuinely want two independent hosts on one machine, give each its own state directory and port (HOLARYN_STATE_DIR=... holaryn serve --port ...).

Updater says it can't fetch release JSON

Versions before 0.6.0 predate the live update channel, so their "Check for updates…" fails with "Could not fetch a valid release JSON from the remote." This was fixed in 0.6.0 — update manually once: download the latest installer from the Releases page and install it over the old version. From 0.6.0 onward, in-app updates work normally.

Note the updater follows the stable channel only: dev-beta builds update to the next stable release, not to newer betas.

Windows service won't start or state looks read-only

holaryn service status prints the OS service state plus the host's own status, and warns when another process (like the desktop app) already owns the state directory.

If a direct holaryn serve (including the desktop app's bundled host) hits legacy read-only state under the default C:\ProgramData\holaryn — typically SQLite files created by an older service running as LocalSystem — it recovers automatically: it releases its handles and lock, verifies you are the service's authorized operator, and starts the installed service, which migrates the file permissions and serves the UI. A custom state directory, missing service, or different Windows account gets an actionable repair error instead.

Useful commands (elevated PowerShell):

holaryn service status --platform windows
sc.exe query holaryn
sc.exe qfailure holaryn
Get-Content C:\ProgramData\holaryn\logs\host.log -Wait

More in Running the agent.

Memory warns about the hash embedder

Out of the box, memory recall is keyword-only — the built-in hash embedder needs no downloads but does no semantic matching, and the agent warns about it. To get recall by meaning, open Settings → Memory → Semantic memory and either:

• pick Local semantic (FastEmbed) — fully offline after a one-time ~70 MB model download; requires the extra:

pip install "holaryn-agent[fastembed]"
# or from the terminal against an installed agent:
holaryn memory install-extra fastembed

• or pick Ollama server if you already run Ollama (pull an embedding model there first).

Then Reindex so existing memories get vectors from the new embedder — from the same panel or:

holaryn memory reindex

See Memory for the full picture.

Dev builds only offer an NSIS installer (no MSI)

Expected. A dev pre-release version (X.Y.Z-dev.g<sha>) cannot drive an MSI — the MSI ProductVersion field is numeric-only — so dev-branch builds produce the NSIS …-setup.exe only. Stable releases ship both NSIS and MSI. If you need an MSI, install a stable release.

I need to switch back from the Harbor workbench

Choose Use classic navigation at the bottom of the left workbench rail. The page reloads with
the prior flat navigation. Routes, chats, projects, settings, and application data do not change.
Choose Use Harbor workbench in the classic header to return.

The choice is a local browser preference named holaryn-workbench-shell; it is not synchronized and
does not alter the host. If the new shell cannot be operated at all, open the browser's developer
console for the local Holaryn page, run the following command, and reload:

localStorage.setItem("holaryn-workbench-shell", "classic");

To restore the default later:

localStorage.removeItem("holaryn-workbench-shell");

Report the original problem before leaving the workaround in place. Include the browser, operating
system, zoom level, input or assistive technology, and the exact workspace where it occurred.

A task package will not export, import, or rerun

Task-package failures use stable task-package.* error codes. Keep the original
archive unchanged while investigating:

• Export rejects CHOOSE:* review values by design. Replace every placeholder with
  an allowed action from its matching scan finding, then rerun export with the same
  plan, report, canary environment variables, and inputs.
• Inspect or import failures for limits, duplicate names, unsafe paths, unexpected
  entries, digest/signature mismatch, or malformed JSON mean the archive is
  untrusted. Do not extract or repair it manually; ask the publisher for a fresh
  package.
• An encrypted failure requires the password environment variable named with
  --password-env; a publisher-trust warning is not removed by encryption.
• A blocked preflight reports all missing or incompatible dependencies and local
  resolutions at once. Importing does not authorize execution. Fork/remap the local
  overlay, provide the required inventory, then run dry-run again.
• rerun-reference requires an exact --confirm "RUN <digest>" value and only runs
  the documented reference workflow. A digest or evidence mismatch is a failed
  reproduction, not a success with a warning.

See Shareable task packages for trust tiers, size limits,
recovery, and the full CLI/UI workflows.

Where the logs live

• Web UI: Settings → Diagnostics has a live log viewer.
• On disk: <state-dir>/logs/host.log (default C:\ProgramData\holaryn\logs\host.log for the Windows service; journalctl -u holaryn.service also works on Linux systemd installs).
• holaryn status shows whether a host is running and where.

Compose container is unhealthy or production startup is refused

Run:

python deploy/compose/manage.py status
python deploy/compose/manage.py logs

Common startup failures are intentional safety checks:

• Production configuration is not ready means the real DNS hostname, certificate-recovery email,
  or exact allowed hostname is still missing from .local/deployment.env.
• cannot read ... secret file means the referenced file is absent, empty, or unreadable by the
  non-root container. Re-run manage.py init, then restore its owner-only permissions.
• state/backup directory is not writable by uid 10001 means a bind or external volume has the
  wrong ownership. The documented named volumes are initialized with the correct owner.
• another deployment instance holds the migration lock means another container still uses the
  same state volume. Stop it; do not delete the lock file.
• An unhealthy /readyz with onboarding required is still a responsive new install; use the
  printed onboarding URL. A process crash or inaccessible secret/writable mount appears in
  manage.py logs.

If an update fails, stop the candidate and follow the fresh-volume restore procedure. Do not start
an older image directly against state already migrated by the candidate. See
Self-host with Docker Compose.

Reporting issues

File bugs and feature requests on GitHub: https://github.com/synergentic/holaryn-agent/issues. Include your version (holaryn --version or Help → About in the desktop app), your OS, and the relevant lines from the log viewer. The desktop app's Help menu has a direct issue-reporting entry.

Related pages

• Installation — install-time problems (PATH, wheels, antivirus flags on uv.exe).
• Running the agent — hosts, services, and state directories.
• Settings — where every panel mentioned above lives.