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, it does not see your per-user environment. Store the API key in Settings → Providers & Models (Actions → Set API key) instead: the secret store keeps it in the state directory, which only you, SYSTEM and Administrators can read. Do not set API keys as machine-wide (system) environment variables, because every account on the computer can read them. If you must use a variable, set it for your own account only and run the host as yourself (holaryn serve or the desktop app); the service cannot see it.

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 ...).

The browser shows a Holaryn error page

When the browser opens an address the host cannot serve, the host answers with a short page in
the browser's language (English, Spanish or French) instead of bare text:

Holaryn does not answer at this address: the host name in the address is not one the host
was started to answer (a DNS-rebinding guard). Open the address holaryn serve printed, usually
http://127.0.0.1:8765/, or start the host with --allowed-host <name> to use another name.
This address is only for app previews: mcp-app.localhost only frames MCP Apps inside
Holaryn's own pages. Open Holaryn at its usual address.
The Holaryn web interface is not installed: the host runs but its web interface files are
missing. Reinstall Holaryn; from source, run npm ci and npm run build in
src/holaryn_agent/webui/frontend. The holaryn commands still work.
Page not found and This address needs a signed-in Holaryn page: the address is
mistyped, or it only works from a signed-in Holaryn page (a download link works once). Go back
to Holaryn and try again from there.
This address is not a page: the address is one Holaryn uses for actions (such as /input),
not a page you can open. Go to Holaryn home.
Holaryn cannot read this address: the address is incomplete or contains something Holaryn
cannot use. Check the address.
Holaryn refused this request: Holaryn cannot show a page at this address. Go to Holaryn
home.
Holaryn could not answer: something went wrong while the host handled the request. Reload
the page; if it happens again, look in the Holaryn log (see Where the logs live).
MCP sign-in complete, MCP sign-in was declined, MCP sign-in could not complete and
MCP sign-in is unavailable: the result of an MCP server sign-in in the system browser.
Return to Settings in Holaryn: refresh the connection status after a completed sign-in, try
again after a declined one, and review the connection after one that could not complete or was
unavailable.

The page says "Holaryn Agent has not started yet"

The page loaded but its scripts did not run within five seconds: they were blocked, a browser
extension stopped them, the host went away mid-load, or a saved copy points at scripts an update
replaced. Reload the page; if that does not help, check that the host is running and reachable
from this device, then open Holaryn again. With JavaScript turned off for the site, the page says
it needs JavaScript instead.

holaryn serve normally makes a new sign-in each time it starts, so a browser tab opened before a restart is no longer accepted. The tab then says "This tab's sign-in has expired": "Holaryn no longer accepts the sign-in this tab was opened with. This usually means Holaryn was restarted." Reloading the tab, or pressing anything on it, cannot fix that.

To continue, run holaryn open in a terminal on the computer where Holaryn runs, or open the new sign-in link that holaryn serve printed. You can then close the old tab.
If you use Holaryn from another device, run holaryn open --print on the computer where Holaryn runs and open the link it prints on your device.
If the chat, Settings, a canvas, Code or an operator page had already loaded, it stays on screen with the notice above it until you close or reload it, so you can copy anything you still need, such as an unsent message. In the chat, the notice takes the place of the connection notice and keeps its Retry connection button; while the sign-in is refused, a press says the sign-in has expired again, and if Holaryn accepts the sign-in again (for example a host started with a fixed token), a press says "Reconnected." and the notice goes.
In the desktop app the window says "Holaryn needs to be restarted" instead: quit Holaryn and open it again. Reloading the window does not help.

A tab opened without any sign-in (for example a link pasted into a new tab) says "This tab is not signed in" instead; open the page from your signed-in Holaryn window or from a sign-in link.

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.

The updater follows the channel selected under Settings → System → Software updates. Stable is
the default; Beta and Nightly subscribers may receive releases from their selected channel as well
as any newer, more stable channel. Prerelease checks use that release's exact signed latest.json
asset because GitHub's /releases/latest shortcut intentionally excludes prereleases.

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

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:

holaryn memory install-extra fastembed

Or run the installer again with fastembed added to the extras you use, or run
uv sync --extra fastembed in a source checkout.

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.

Choose Use top navigation in the sidebar to switch to the compact top bar.
To return, open All features (Ctrl+Shift+K) and choose Use sidebar navigation.
Routes, chats, projects, settings, and application data do not change. Older builds called these
layouts Classic and Harbor; Harbor is an internal design name.

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.

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.

← Previous Privacy-reviewed training data Next → Run usage diagnostics

Troubleshooting