What causes "hermes update failed (exit {:?}). See {} for details." in NousResearch/hermes-agent?

Open ~/.hermes/logs/update.log and read the tail — the actual error is there, not in this message.

NousResearch/hermes-agent · error · anyhow::Error

hermes update failed (exit {:?}). See {} for details.

Error message

hermes update failed (exit {:?}). See {} for details.

What it means

Stage-2 failure of the update flow: the `hermes update` child exited with an exit code that is neither success nor the 'still running' sentinel. The real cause is inside the CLI's own log — the message points at ~/.hermes/logs/update.log — so this wrapper just surfaces the exit status and the log path.

Source

Thrown at apps/bootstrap-installer/src-tauri/src/update.rs:479

                    .join("logs")
                    .join("update.log")
                    .display()
            );
            emit_stage(
                &app,
                "update",
                StageState::Failed,
                Some(update_ms),
                Some(msg.clone()),
            );
            emit(
                &app,
                BootstrapEvent::Failed {
                    stage: Some("update".into()),
                    error: msg.clone(),
                },
            );
            return Err(anyhow!(msg));
        }
    }

    // ---- stage 3: hermes desktop --build-only ----------------------------
    // `hermes update` deliberately does NOT build apps/desktop (it installs
    // repo-root deps with --workspaces=false). This is the rebuild it skips.
    emit_stage(&app, "rebuild", StageState::Running, None, None);
    let started = Instant::now();
    let rebuild_args: Vec<String> = vec!["desktop".into(), "--build-only".into()];
    let mut rebuild = run_streamed(
        &app,
        &hermes,
        &rebuild_args,
        &install_root,
        &child_env,
        Some("rebuild"),
    )
    .await?;

View on GitHub (pinned to c896c09c42)

Solutions

Open ~/.hermes/logs/update.log and read the tail — the actual error is there, not in this message.
Fix the root cause it shows (reconnect network, clean the tree, free disk).
Re-run the update; if the venv is corrupted, re-run the bootstrap installer to repair.
If it keeps failing on the same step, capture the log excerpt and report it rather than retrying blindly.

Defensive patterns

Strategy: try-catch

Try / catch

// Distinguish sentinel exit codes from real failures; always point the user at update.log.
match status.code() {
    Some(0) => { /* success */ }
    Some(code) if code == STILL_RUNNING_SENTINEL => { /* see [547]: retry after shutdown */ }
    Some(code) => {
        let log = crate::paths::hermes_home().join("logs").join("update.log");
        emit_stage(&app, "update", StageState::Failed, Some(ms),
            Some(format!("hermes update failed (exit {code}). See {} for details.", log.display())));
    }
    None => { /* killed by signal: see [551] */ }
}

Prevention

Read the tail of ~/.hermes/logs/update.log first — the wrapper message carries no root cause.
Keep the install tree clean (no local modifications) so git-based updates don't conflict.
Verify network/proxy access to package sources before updating on locked-down machines.

When it happens

Trigger: `hermes update` failing on git operations (dirty tree, detached pin, network), pip/dependency install failures, venv corruption, or disk-full while updating packages; any non-zero, non-sentinel exit code from the CLI subprocess.

Common situations: Offline or flaky network during dependency install; local modifications in the install tree conflicting with git pull; Python version mismatch after an OS upgrade broke the venv; corporate proxy blocking pypi/github.

Related errors

AI-assisted analysis of NousResearch/hermes-agent@c896c09c42 (2026-08-14). Data as JSON: /api/errors/03583803081efd6a. Report an issue: GitHub.