Windows Desktop backend port announcement timeout (45000ms) after provider-isolated boot test

[ahmedmahmoud77755-gif]

Summary

Hermes Desktop on Windows fails to start because the backend never announces its port before the desktop timeout.

Main error:

Desktop boot failed: Timed out waiting for Hermes backend port announcement (45000ms)

This looks related to, but not fully covered by:

• Windows Desktop update can leave stale app.asar with old 45s backend timeout while source has 90s timeout #53770 — stale packaged app.asar keeping old 45s backend timeout
• [Bug]: Windows 启动超时 + 黑框闪烁 #54528 — Windows startup timeout / cold Python import and Defender scanning
• [Bug]: Desktop GUI flashes empty dialog/overlay on startup (boot failure loop) #53685 — desktop startup loop / backend port announcement timeout

I also see a renderer-side error:

RangeError: Maximum call stack size exceeded

That may be separate from the backend startup timeout.

Environment

• Hermes version: 0.18.0
• OS: Windows 10.0.26200
• Install layout: Hermes executable located under the local app data Hermes agent virtualenv Scripts directory
• Startup modes attempted: Desktop and serve

Troubleshooting already attempted

• Restarted Hermes.
• Restarted the machine.
• Cleared session data by renaming session/state stores.
• Ran the agent directly using hermes serve.
• Performed a provider-isolated boot test by disabling failing/depleted/invalid providers.
• Restored original config after testing.
• Reproduced with an empty workspace.

Provider-isolated boot test result

• Provider-isolated boot test: attempted
• Result: FAIL
• Backend port announcement: not observed / not programmatically verifiable
• Agent connection: unavailable

This suggests the failure is not only provider billing/auth noise.

Expected behavior

Hermes Desktop should start, the backend should announce its port, and the desktop should connect to the backend without timing out.

Actual behavior

The desktop waits for the backend port announcement and times out after 45 seconds. The agent is not reachable afterward.

Questions

1. What is the official diagnostic path for backend port announcement timeouts on Windows?
2. Which backend log should contain the port announcement event?
3. Could this be caused by a stale packaged app.asar still using the old 45-second timeout path?
4. Should HERMES_DESKTOP_PORT_ANNOUNCE_TIMEOUT_MS be used as a workaround, and where should it be set for Windows Desktop?
5. Can Windows Defender / cold Python import scanning cause this timeout even after provider isolation?
6. Which cache/state folders are safe to clear after backup?
7. Is there a minimal safe startup mode with all providers disabled?
8. Which ports must be free for gateway/backend startup?
9. Is the current local app data virtualenv install layout expected for desktop mode?
10. Can RangeError: Maximum call stack size exceeded persist after clearing session data, and could it block the desktop from recovering?

Sanitization note

No API keys, tokens, provider credentials, local config contents, or service-account files are included in this report.

[ahmedmahmoud77755-gif]

Update from issue submitter: this is the same class of issue as #54528 — Windows cold-start (Defender scanning 14k+ .pyc files) exceeds the 90s default. The maintainer in #54528 explicitly confirmed \HERMES_DESKTOP_PORT_ANNOUNCE_TIMEOUT_MS\ is the supported override. Local config.yaml (60 lines) does NOT have the empty \context_file_max_chars\ / \max_concurrent_sessions\ sections reported in #53685, so this report isolates the cold-start timeout specifically.

Machine: Windows 10.0.26200, Hermes 0.23.2+ae3697e64. Setting the env var to 180000ms clears the timeout locally; reporting for visibility so the next Desktop build can consider either a longer default or Defender-cache-aware startup.

[Oceaneyes123]

Temporarily, you can try this command:

hermes desktop --build-only

This works for me ✅

[ahmedmahmoud77755-gif]

Thanks @Oceaneyes123 for the suggestion. To clarify for anyone landing here: --build-only builds the Electron app but does NOT launch it (per hermes desktop --help), so it's not a way to actually run Hermes — it's useful for installer/CI flows.

What works to actually launch and avoid the cold-start timeout in this situation is:

1. HERMES_DESKTOP_PORT_ANNOUNCE_TIMEOUT_MS=180000 hermes desktop --skip-build — skips npm/build, launches the already-unpacked app, and doubles the backend-wait window to 180s, giving Defender time to scan the 14k+ .pyc files.
2. Once cold cache is warm, you can drop back to default 90s.

Per the maintainer in #54528, HERMES_DESKTOP_PORT_ANNOUNCE_TIMEOUT_MS is the supported override for this exact cold-start/Defender/cache readiness scenario.

[GottZ]

This was generated by AI during triage.

Summary

One closed PR references this issue complex through related issue #54928, but its complete diff only makes DEFAULT_FETCH_TIMEOUT_MS platform-specific (30 seconds on Windows, 15 seconds elsewhere); it does not modify the backend port-announcement deadline reported in #59205. The submitter reports that setting HERMES_DESKTOP_PORT_ANNOUNCE_TIMEOUT_MS to 180000 resolved the cold-start failure locally, but the visible record contains no authoritative documentation or maintainer statement confirming that override’s support status.

Related pull requests

• fix: increase desktop fetch timeout to 30s on Windows (#54928) #55479 [closed] unrelated — (+1/-1) — unrelated: The diff changes only DEFAULT_FETCH_TIMEOUT_MS from 15 seconds to 30 seconds on Windows, with no usage or control-flow evidence establishing an effect on the backend port-announcement deadline. Although closed, fix: increase desktop fetch timeout to 30s on Windows (#54928) #55479 remains relevant as a historical comparison for the related Desktop boot timeout too short (15s) — frequent startup failures on Windows #54928 timeout; the contributor review says its intended behavior was superseded on main by the broader 90-second port-announcement and 45-second readiness paths.

Suggested consolidation

Merge none — #55479 does not address #59205’s backend port-announcement timeout and is already closed after a contributor determined that its #54928 behavior was implemented more broadly on main. Keep #59205 tracked separately for the reported cold-start timeout beyond the current default and for authoritative diagnostics or a targeted fix; there are no duplicate PRs to close.

Complex graph

flowchart LR
    classDef open fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
    classDef merged fill:#dcfce7,stroke:#15803d,color:#14532d
    classDef closed fill:#e5e7eb,stroke:#6b7280,color:#1f2937
    classDef unverified fill:#f3f4f6,stroke:#9ca3af,color:#374151
    classDef best stroke-width:3px,stroke:#b45309
    classDef target stroke-width:3px,stroke:#4338ca
    I54928(["issue #54928 (closed)"])
    I59205(["issue #59205 (open)"])
    P55479["PR #55479 (closed)"]
    P55479 -->|best fix| I54928
    class I54928 closed
    class I59205 open
    class I59205 target
    class P55479 closed
    class P55479 best
    click I54928 "https://github.com/NousResearch/hermes-agent/issues/54928"
    click I59205 "https://github.com/NousResearch/hermes-agent/issues/59205"
    click P55479 "https://github.com/NousResearch/hermes-agent/pull/55479"

Loading

Graph: solid arrow = fixes / best fix, dashed arrow = partial or unverified (see edge label); boxed group = PRs duplicating each other; amber border = best fix; indigo border = target; gray node = closed or no verify verdict yet (state tag in the node label).

Cross-PR triage: Reviewed 1 pull request and 2 issues in this complex. Each diff was read against this issue; Assessment working set: <1 kB of PR diffs, 5 kB of issue/PR text, 4 kB of discussion (5 comments), 3 verify verdicts. verdicts reflect diff content, not PR titles. Part of an automated triage batch.