| Failure | Symptom | Documented root cause | Fix |
|---|
| Cron silent skip | Job stops firing after a model change | Unpinned jobs snapshot the global provider and model and fail closed when the default changes (https://hermes-agent.nousresearch.com/docs/user-guide/features/cron, https://github.com/nousresearch/hermes-agent/issues/44585) | Pin provider and model explicitly via the documented update action with provider and model parameters |
| Recursive schedule attempt | cron create fails inside a cron run | Cron management tools are disabled inside cron executions to prevent runaway scheduling (https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) | Use a pre-scheduled one-shot, a gateway hook, or an external scheduler instead |
| Workdir job clobbered | Two workdir-scoped jobs step on each other's state | The cron worker applies job workdir through process-global terminal state (https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) | Serialize workdir jobs by spreading their schedules or drop the workdir for one of them |
| Memory write refused | memory replace returns a length error | MEMORY.md is capped at 2,200 chars and does not auto-compact (https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) | Consolidate or remove an entry in the same turn before retrying |
| Memory replace ambiguous | memory replace old_text=<substring> errors on multiple matches | Substring matching rejects ambiguous matches to prevent wrong-entry edits (https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) | Use a more specific substring or split the target entry first |
| Subagent returns nonsense | The delegated child guesses at file paths, errors, or runtimes | Subagents begin with a fresh conversation and have zero knowledge of the parent's history (https://hermes-agent.nousresearch.com/docs/user-guide/features/delegation) | Pass file paths, line numbers, exact error text, and runtime in the context block |
| Subagent returns too much | The parent's context floods with subagent detail | No return-shape constraint was specified in the goal field | Specify the structured summary shape in the goal (what was done, what was found, files modified, issues) |
| MCP install succeeds, server unreachable | Tools show as installed but calls fail at runtime | The documented install flow writes the manifest's defaults and skips probing when the probe fails (https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) | Re-run hermes mcp configure <name> once the server is reachable to refine the tool allowlist |
| Browser session expires mid-flow | A long navigation flow dies after several minutes | Cloud browser sessions have a TTL; the default and override are documented (https://hermes-agent.nousresearch.com/docs/user-guide/features/browser) | Raise the TTL via FIRECRAWL_BROWSER_TTL for Firecrawl or split the flow into shorter sessions |
| Local browser required for localhost | Cloud browser cannot reach a local development URL | Cloud browsers cannot reach LAN or loopback addresses | The hybrid routing path auto-spawns a local Chromium sidecar for private addresses (https://hermes-agent.nousresearch.com/docs/user-guide/features/browser) |
| Provider rate limit mid-task | Calls start returning 429 and the task stalls | The primary model is rate-limited and no fallback is configured | Configure fallback_providers per the documented schema (https://hermes-agent.nousresearch.com/docs/user-guide/features/fallback-providers) |
| OAuth token expired | Scheduled jobs stop working overnight | OAuth tokens need refresh, and unattended jobs cannot re-authenticate interactively | Use hermes setup --portal so refresh is automatic; the docs explicitly recommend it for unattended runs (https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) |
| Context reference rejected | @file:<path> expansion fails with "hard limit" message | Context references have a soft limit at 25 percent of context length and a hard limit at 50 percent (https://hermes-agent.nousresearch.com/docs/user-guide/features/context-references) | Use line ranges, split the message, or read the file in a subagent |
| Subagent toolset overreach | A delegated child takes a side effect it should not have | The toolset restriction field was left implicit and the subagent inherited the parent's full toolset | Restrict toolsets explicitly in the delegate_task call (https://hermes-agent.nousresearch.com/docs/user-guide/features/delegation) |
The pattern across the list is that every failure has a documented behavior behind it. That is the good news. The bad news is that the symptom is rarely the name of the failure; the work of an operator is to read the symptom, map it to the subsystem, and look up the documented behavior.
Cron fail-closed and the silent skip
The cron fail-closed behavior is the single highest-impact failure on the list because it is silent by design (https://hermes-agent.nousresearch.com/docs/user-guide/features/cron, https://github.com/nousresearch/hermes-agent/issues/44585). The job does not error visibly; it just stops firing, and the operator notices only when the morning brief does not arrive. The fix is to pin the provider and model at job creation time, or to update the job when you deliberately change the global default.
A useful operational discipline is to treat any provider or model change as a cron change. The same operator runbook that swaps the global default should also enumerate every unpinned job and decide whether each one should be pinned, updated, or left to skip. That step is easy to skip because the change "looks" global, but its blast radius is local to every job that did not pin.
Memory overflow at 2,200 characters
The memory layer is bounded by design and the bound is small (https://hermes-agent.nousresearch.com/docs/user-guide/features/memory). The agent will not silently truncate; it will return an error and ask the same turn to make room. The operator's job is to set up a periodic review cadence so that memory does not become a graveyard of one-off facts. The healthy pattern is to consolidate aggressively when memory crosses about 70 percent of the cap, not when it hits 100 percent and breaks the next write.
A second operator pattern is to be deliberate about what goes in MEMORY.md versus USER.md versus skills. The three layers are not interchangeable, and overstuffing one because it is easy to write to will eventually produce the exact failure this row describes.
Subagent context starvation
The subagent context starvation failure is the one that costs the most operator time per incident, because the symptom is "the subagent did the wrong thing" rather than "the subagent failed." The documented fresh-conversation rule means the parent cannot rely on prior context (https://hermes-agent.nousresearch.com/docs/user-guide/features/delegation). The fix is to write the context block as a self-contained briefing, and to specify the return shape in the goal field. Builders who internalize this rarely hit the failure; builders who do not hit it constantly.
A useful diagnostic is to read the last ten delegations your agent made and check whether each one would still be executable by a fresh engineer sitting at a clean checkout, reading only the context block. If the answer is no, the delegation was starving.
MCP server probe failure at install time
The MCP install flow is documented as tolerant: if the server probe fails, the install still succeeds and falls back to the manifest's defaults or to no filter at all (https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp). That tolerance is the source of the failure on this row, because the operator does not learn about the probe failure until the first tool call fails at runtime. The documented remedy is to re-run hermes mcp configure <name> once the server is reachable, which walks through the tool allowlist with the operator present.
The operational discipline is to verify the probe during install, not after. If the catalog entry's transport requires OAuth or a backing service, complete the OAuth dance before you treat the install as finished. The dashboard surfaces the manifest source, transport, and bootstrap commands per entry so the operator can inspect before clicking Install (https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp).
Browser session timeout in the middle of a flow
The cloud browser modes have a TTL, and the default and override are documented per backend (https://hermes-agent.nousresearch.com/docs/user-guide/features/browser). The failure mode is that a long navigation flow that takes longer than the TTL expires mid-flow, and the next browser call gets a fresh session that no longer has the cookies, local storage, or focus from the previous one. The fix is to either raise the TTL via the documented override or to design flows to complete within the TTL.
The hybrid routing path documented for the browser toolset solves a related but distinct problem: when the operator is developing locally, cloud browsers cannot reach loopback or LAN addresses (https://hermes-agent.nousresearch.com/docs/user-guide/features/browser). The documented behavior is that Hermes auto-spawns a local Chromium sidecar for those addresses while continuing to use the cloud provider for public URLs in the same conversation.
Provider fallback exhaustion
The fallback system has three documented layers (https://hermes-agent.nousresearch.com/docs/user-guide/features/fallback-providers). Credential pools rotate keys for the same provider. Primary model fallback switches provider:model pairs. Auxiliary task fallback handles side tasks like vision and compression independently. Each layer addresses a different failure mode, and an operator who configures only the first will still hit the second when the provider as a whole is degraded.
The useful discipline is to configure at least one primary fallback and to keep it on a different provider than the primary. A primary on OpenRouter with a fallback on a direct provider is the common dependable configuration, and the documented fallback chain can carry multiple entries (https://hermes-agent.nousresearch.com/docs/user-guide/features/fallback-providers).
Context reference hard limit refusal
The context reference system has a soft limit at 25 percent of context length and a hard limit at 50 percent (https://hermes-agent.nousresearch.com/docs/user-guide/features/context-references). When the expansion would exceed the hard limit, the reference is refused and the original message is returned unchanged. The documented mitigations are line ranges, splitting the message, or pushing the read into a subagent that returns only a summary (https://hermes-agent.nousresearch.com/docs/user-guide/features/context-references, https://hermes-agent.nousresearch.com/docs/user-guide/features/delegation).
The failure presents as "the agent did not see the file I attached." The diagnostic is to count how much context the references would inject and to compare against the documented thresholds. The fix is structural rather than tool-level; redesign the reference shape rather than trying to raise the limit.
A triage routine for unknown failures
When a new failure appears that is not on the list, the documented triage path is the same in every subsystem. First, identify which subsystem the symptom belongs to (cron, memory, delegation, MCP, browser, fallback, context references). Second, look up the documented behavior for that subsystem and find the closest match. Third, read the relevant section of the public docs and the repository source to confirm the failure mode. Fourth, apply the documented fix or open an issue if the behavior is undocumented.
The order matters. The hardest trap is to start at "what should the agent do" and reason backward to a fix. Agents are generalists; subsystems are specific. The fix lives in the subsystem.
A reliability review is most useful when it answers three questions: which subsystem is degrading, whether the degradation is above the documented threshold, and what changes next. The metrics below are a starting point. Review them weekly for the first month, then monthly once the system has been quiet.
| Metric | Source subsystem | Threshold | Promotion gate |
|---|
| Cron jobs that silently skipped in the last 7 days | Cron | More than 0 | Pin provider and model, or accept the skip explicitly |
| Memory write refusals in the last 7 days | Memory | More than 0 | Consolidate or remove an entry to make room |
| Subagent returns that needed rework | Delegation | More than 1 in 10 | Strengthen the context block template |
| MCP install follow-ups needed in the last 30 days | MCP | More than 0 | Tighten install verification before treating entries as ready |
| Provider rate-limit responses in the last 24 hours | Provider fallback | More than 5 percent of total calls | Add or change the fallback chain |
| OAuth refresh errors in the last 7 days | Auth | More than 0 | Switch unattended jobs to documented Portal OAuth |
FAQ
What is the first thing to check when a cron job stops firing?
Check whether the job is pinned to a provider and model. If it is not, the documented fail-closed behavior may be the cause (https://hermes-agent.nousresearch.com/docs/user-guide/features/cron, https://github.com/nousresearch/hermes-agent/issues/44585).
Why does memory replace sometimes refuse my edit?
The replace action is bounded by the 2,200-character cap and uses substring matching that rejects ambiguous matches (https://hermes-agent.nousresearch.com/docs/user-guide/features/memory). Make the substring unique and shorten the new content if the cap is the issue.
The install flow falls back to the manifest defaults when the probe fails (https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp). Re-run hermes mcp configure <name> once the server is reachable to walk through the allowlist.
The reliability test
A production Hermes Agent deployment is reliable when its operator can name the failure mode behind any incident, point to the documented behavior that explains it, and apply a known fix without improvising. The fourteen failures above are the ones that recur often enough to be worth memorizing; everything else can be triaged through the routine.
A reliability review most teams skip is the one where they walk through the past month's incidents and ask whether each one had a documented behavior the operator could have cited. That audit is the source of the next iteration of the failure register, and the implementation tradeoff it surfaces is the difference between a runbook that ages well and one that goes stale in a quarter.