Hermes venv missing at ${VENV_ROOT}. Re-run the desktop inst

Error message

Hermes venv missing at ${VENV_ROOT}. Re-run the desktop installer or `scripts/install.ps1` to rebuild it.

What it means

Thrown in ensureRuntime when the venv Python interpreter at VENV_ROOT does not exist while the source checkout itself looks complete (no bootstrap-needed sentinel either). Per the comment, activeRuntimeState() should guarantee source + importable hermes_cli before this point, so hitting it means a broken invariant — typically the user or a cleanup tool deleted the venv from a valid checkout.

Source

Thrown at apps/desktop/electron/main.ts:4109

    throw new Error(
      'Git for Windows is required for Hermes on Windows (provides Git Bash, ' +
        "which the agent's terminal tool uses). Install it from " +
        'https://git-scm.com/download/win or run `winget install -e --id Git.Git`, ' +
        'then relaunch Hermes.'
    )
  }

  const venvPython = getVenvPython(VENV_ROOT)

  if (!fileExists(venvPython)) {
    // No venv at the expected location AND no bootstrap-needed sentinel
    // means we have a half-installed checkout: .git exists, source files
    // exist, but venv is missing or broken. This shouldn't happen in
    // normal flow because activeRuntimeState() requires isHermesSourceRoot()
    // plus an importable hermes_cli before it hands back the active runtime.
    // If we hit this, the user (or a deleted venv) broke the invariant; tell
    // them to re-run the install.
    throw new Error(
      `Hermes venv missing at ${VENV_ROOT}. Re-run the desktop installer or ` + '`scripts/install.ps1` to rebuild it.'
    )
  }

  backend.command = getVenvPython(VENV_ROOT)
  backend.label = `Hermes at ${ACTIVE_HERMES_ROOT} (venv: ${VENV_ROOT})`
  updateBootProgress({
    phase: 'runtime.ready',
    message: 'Hermes runtime is ready',
    progress: 82,
    running: true,
    error: null
  })

  return backend
}

// Assemble a single-file multipart/form-data body (FastAPI `UploadFile`

View on GitHub (pinned to c896c09c42)

Solutions

Re-run the desktop installer or scripts/install.ps1 to rebuild the venv.
Alternatively create the venv manually at VENV_ROOT and pip install -e the checkout, matching what install.ps1 does.
Verify getVenvPython(VENV_ROOT) path exists (e.g. VENV_ROOT/Scripts/python.exe on Windows) after rebuild.

Defensive patterns

Strategy: validation

Validate before calling

const fs = require('fs')
const venvPython = getVenvPython(VENV_ROOT)
if (!fs.existsSync(venvPython)) {
  await runInstallerToRebuildVenv()
}

Try / catch

try {
  await ensureRuntime(backend)
} catch (e) {
  if (/venv missing/.test(e.message)) await offerVenvRebuild()
  else throw e
}

Prevention

Never delete the venv under the install root
Let install.ps1 own venv creation
If you rebuild manually, place it exactly at VENV_ROOT

When it happens

Trigger: venv directory under VENV_ROOT deleted, renamed, or corrupted while .git and source files remain; interrupted install that created the checkout but not the venv; disk cleanup tools removing 'unused' virtualenv folders.

Common situations: Manual venv deletion to 'save space'; antivirus quarantining python.exe; partial installs after an installer crash.

Related errors

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