Where Hermes + Paperclip Agents Break (and the Fixes)

Summary:

1. The real failure modes of a Hermes + Paperclip stack, grouped into three categories.
2. The three cited GitHub bugs, with status, so you know which still bite.
3. The security and cost traps that are config mistakes, not bugs.
4. A copy-paste triage checklist plus the fixes that hold.

The AI agent failure modes that cost you a weekend are not mysterious, and they are not fabricated war stories. They are specific, they are documented, and most of them have an issue number. When you compose Hermes Agent with the Paperclip control plane, the failures fall into three buckets: composition bugs in the glue between the tools, config traps you set yourself, and universal LLM problems that hit any agent runtime. Here is the whole matrix, then the fixes that actually hold.

What are the failure modes, at a glance?

The failures are real. The fixes are specific. No fabricated war stories. Here is the full set:

Three categories, ten modes. The composition bugs are the ones unique to wiring these two tools together, so start there.

The session-ID loop (the one that wastes a day)

The most common first-run failure is an open bug. Straight from the tracker:

#1160: hermes-local adapter: invalid session ID stored in sessionParams causes infinite ‘Session not found’ loop (open). The adapter stores any string the session-ID parser returns without validating its format. When Hermes prints an unexpected token (the reported example was the word from) that matches the session-ID regex, the adapter persists it and passes --resume from on the next heartbeat. Hermes answers Session not found: from, the adapter re-stores the bad ID, and runs finish in 2-3 seconds without doing real work.

Source: paperclipai/paperclip#1160, open as of this writing. The detection signal is the tell: heartbeats that complete in two or three seconds while accomplishing nothing. The fix is one field:

"adapterConfig": {
  "model": "openrouter/qwen/qwen-2.5-72b-instruct",
  "persistSession": false
}

Start every new agent with persistSession: false. Turn persistence on only after the agent runs clean.

The two other cited bugs

Embedded Postgres on WSL2 (paperclip#1032, open). onboard completes, but run fails and the logs show PostgreSQL init errors. Skip the embedded database and point at a real one on port 5432:

docker run -d --name paperclip-postgres \
  -e POSTGRES_PASSWORD=paperclip -e POSTGRES_DB=paperclip \
  -p 5432:5432 postgres:16
export DATABASE_URL="postgres://postgres:paperclip@localhost:5432/paperclip"
npx paperclipai run

Stale api_mode on a provider switch (hermes-agent#3685, resolved). This one is fixed in current Hermes, so it is here as a class of problem, not an active bug. If a provider switch does not take, the recipe is generic: clear the cached auth (hermes logout <old>), re-authenticate, restart any long-running process, and verify with a fresh hermes chat -q "test". Do not present a resolved bug as a live one; that is how troubleshooting sections lose trust.

The config traps (your mistakes, not bugs)

local_trusted exposure. Paperclip’s default local_trusted mode has no login and assumes loopback only. Expose it on a network and anyone who reaches the machine has full admin. Check your mode before binding anywhere but 127.0.0.1:

npx paperclipai env | grep -i mode

The fix is to switch to authenticated mode the moment client data or network exposure enters the picture. Never bind to 0.0.0.0 in local_trusted.

Unrestricted filesystem access. Hermes’s local terminal backend gives the agent your user’s full filesystem access: SSH keys, browser cookies, git repos. It is fine in isolation and dangerous the moment an agent processes untrusted input. Switch that agent to the docker backend, or restrict it to enabledToolsets: ["file", "web"] so it cannot spawn a shell at all.

The universal LLM failures (manage, don’t fix)

These hit any agent runtime. The big one is runaway cost: an agent loops on an error, retries, and burns tens of dollars on a task that should cost cents. You do not fix this, you bound it:

"adapterConfig": { "timeoutSec": 300, "maxIterations": 50 }

timeoutSec caps wall-clock time per heartbeat; maxIterations caps tool calls. While you investigate a runaway, crank HEARTBEAT_SCHEDULER_INTERVAL_MS up or disable the scheduler entirely. Then set a provider-side billing alert as the last line of defense. The other universal modes follow the same logic: split oversized tasks into smaller issues to dodge context overflow, gate client-facing output behind a human approval and an editor agent to catch hallucinated citations, and use provider abstraction so a deprecated model is a one-line config change, not a rewrite.

What should you actually do?

When something breaks, work the triage checklist in order. Most problems surface in the first three steps:

1. Run npx paperclipai doctor and hermes doctor. They surface config and dependency errors fast.
2. Read the activity log: npx paperclipai activity list --company-id <id>. Look for repeating patterns or long gaps.
3. Check the issue state: npx paperclipai issue get PC-N. Confirm where it actually is and who owns it.
4. Search both issue trackers for your exact error message. Someone has probably hit it.

The bottom line

• Three of these failures have issue numbers; one of those three is already resolved. Knowing the status is the difference between fixing a real bug and chasing a ghost.
• Most “AI agents are unreliable” takes are really “I never set a timeout.” Bound cost with timeoutSec and maxIterations, and the worst case is a wasted heartbeat, not a wasted paycheck.
• Composition bugs get fixed upstream, config traps are on you, and universal LLM failures are the price of the technology. Stay current on versions, restrict by default, and gate anything a human will pay for.