Hermes Desktop startup failure: diagnosing and fixing stale model fallbacks

A recent Hermes Agent Desktop update caused an issue where the desktop application appeared unable to start or log in, even though the local Hermes backend and configured AI provider were working normally.

The visible error was:

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

At the same time, the logs showed that Hermes had actually started its backend successfully:

HERMES_BACKEND_READY port=50465
Hermes backend listening on 127.0.0.1:50465

This created a confusing situation: the Desktop app timed out waiting for its local backend, while the backend was already alive and accessible.

What caused it

The fault had two overlapping parts:

1. A retired OpenRouter model remained in old task routing.
A scheduled task was still attempting to use stealth/ox-alpha, an OpenRouter preview model that had been retired. OpenRouter returned HTTP 404 and directed users to its replacement, z-ai/glm-5.3-flash.

2. Hermes then fell back to an inactive Alibaba Coding Plan model.
The fallback chain still contained qwen3.8-max through alibaba-coding-plan. As the relevant Alibaba entitlement was no longer active, the request failed with:

HTTP 403: Access to model denied
AccessDenied.Unpurchased

The updated primary model was already MiniMax M3, but saved scheduled jobs and fallbacks can retain historical model choices. That meant some jobs continued trying obsolete providers even after the global model was changed.

The safe recovery process

The first priority is to avoid deleting Hermes data. Do not remove or reset:

~/.hermes

This folder contains the Hermes configuration, API credentials, sessions, memories, skills, profiles, cron jobs, logs, and local databases.

Before changing anything, create a backup:

mkdir -p ~/Desktop/hermes-backups
tar -czf ~/Desktop/hermes-backups/hermes-before-fix-$(date +%Y%m%d-%H%M%S).tar.gz ~/.hermes

A successful archive command may display:

tar: Removing leading '/' from member names

That is normal and does not indicate a problem.

Check model routing

Use the Hermes CLI to inspect the active model and fallback chain:

~/.hermes/hermes-agent/venv/bin/hermes fallback list

In this case, the output showed:

Primary: MiniMax-M3 (via minimax)

Fallback chain:
1. qwen3.8-max (via alibaba-coding-plan)

The invalid Alibaba fallback should be removed through the interactive fallback manager:

~/.hermes/hermes-agent/venv/bin/hermes fallback remove

Then check it again:

~/.hermes/hermes-agent/venv/bin/hermes fallback list

The goal is for MiniMax to remain the primary model, with no inaccessible provider left in the fallback path.

Fix scheduled jobs

Scheduled Hermes jobs can retain prior model settings or stop deliberately when Hermes detects configuration drift. List jobs with:

~/.hermes/hermes-agent/venv/bin/hermes cron list

Look for failed jobs using old models or errors such as:

HTTP 403: Access to model denied

or:

global inference config drifted

Pin affected jobs explicitly to the current working provider and model:

~/.hermes/hermes-agent/venv/bin/hermes cron edit JOB_ID --provider minimax --model MiniMax-M3

For example:

~/.hermes/hermes-agent/venv/bin/hermes cron edit 3c006b59e927 --provider minimax --model MiniMax-M3

This updates only the selected job's model routing. It does not delete the job, its schedule, history, skills, delivery settings, or other Hermes data.

Confirm the provider works

A simple one-shot request confirms whether Hermes can reach the configured model outside Desktop:

~/.hermes/hermes-agent/venv/bin/hermes -z "Reply with exactly: Hermes MiniMax test passed"

A successful result:

Hermes MiniMax test passed

confirms that the MiniMax API key, provider configuration, local Hermes runtime, and AI request flow are working correctly.

When Desktop still fails

If the terminal test succeeds but Hermes Desktop still reports a backend port timeout, the problem is likely limited to the Electron Desktop interface rather than the agent, credentials, or stored data.

Run a health check:

~/.hermes/hermes-agent/venv/bin/hermes doctor

Useful indicators include:

• Configuration version is current
• Required Python packages are installed
• API credentials and config files exist
• SQLite databases are healthy
• Sessions, memory, skills, and cron directories are present
• No deprecated configuration keys are detected

If those checks pass, use Hermes through its terminal interface while the desktop issue is investigated:

~/.hermes/hermes-agent/venv/bin/hermes --tui

Or start the local browser dashboard:

~/.hermes/hermes-agent/venv/bin/hermes dashboard

This retains access to the same sessions, memory, skills, scheduled jobs, and model configuration while bypassing the Desktop application.

Key takeaway

A Desktop boot timeout does not necessarily mean Hermes itself has failed. In this case, the backend was healthy, MiniMax was working, and all local data remained intact. The effective fix was to remove an inaccessible Alibaba fallback, pin legacy scheduled jobs to the active MiniMax model, verify the provider through the CLI, and use the dashboard or terminal UI until the Desktop connection issue is resolved.

Frequently asked questions