heygen-com/hyperframes · error · Error

npx not found. Install Node.js and retry.

Error message

npx not found. Install Node.js and retry.

What it means

Thrown by skillsToolingReady(strict=true) when hasNpx() returns false. The skills installer shells out to `npx skills add ...` (via buildNpxCommand), so npx must resolve and print a version within 5s. In strict mode the missing tool is fatal; in non-strict mode it's logged and the install is skipped.

Source

Thrown at packages/cli/src/commands/skills.ts:224

    error: "npx not found. Install Node.js and retry.",
    reason: "npx_missing",
    report: () => clack.log.error(c.error("npx not found. Install Node.js and retry.")),
  },
  {
    has: hasGit,
    error: "git not found. Install git and retry to add AI coding skills.",
    reason: "git_missing",
    // Skip cleanly rather than letting the upstream clone dump a noisy
    // multi-line `spawn git ENOENT` / "Installation failed" abort.
    report: () => console.log(c.dim("Skipping AI coding skills: git not available.")),
  },
];

/** True if the install can proceed; otherwise reports (or throws, when strict). */
function skillsToolingReady(strict: boolean): boolean {
  for (const tool of SKILLS_TOOLING) {
    if (tool.has()) continue;
    if (strict) throw new Error(tool.error);
    tool.report();
    // Surface the rare best-effort skip (init on a box missing git/npx); the
    // event respects the telemetry opt-out inside trackEvent.
    trackSkillsInstallSkipped({ reason: tool.reason });
    return false;
  }
  return true;
}

// Skill names can originate from a fetched manifest or agent argv, and each is
// spread into a spawn as a `--skill` value — apply the same slug guard as
// runSkillsRemove so a flag-like name can't smuggle into the command. Returns
// null when nothing valid is left to install.
function sanitizeSelection(selection: SkillSelection): SkillSelection | null {
  if (selection === "*") return selection;
  const rejected = selection.filter((n) => !PLAIN_SKILL_NAME.test(n));
  if (rejected.length) {
    clack.log.warn(c.warn(`Skipping unexpected skill name(s): ${rejected.join(", ")}`));

View on GitHub (pinned to c2996c8626)

Solutions

1. Install Node.js (which bundles npx) and ensure it is on PATH: `node -v && npx -v`
2. If on Windows use npx.cmd (buildNpxCommand handles this) — verify it resolves
3. Re-run the command once `npx -v` succeeds
4. For non-interactive init, the install is skipped automatically; run skills later once npx is available

import { execFileSync } from "node:child_process";
function hasNpx(): boolean {
  try { execFileSync("npx", ["--version"], { stdio: "ignore", timeout: 5000 }); return true; }
  catch { return false; }
}

When it happens

Trigger: Calling `hyperframes skills` / `skills update` / `init` with skills enabled on a host where `npx --version` fails (ENOENT or non-zero). The SKILLS_TOOLING loop hits the npx entry, has() is false, and strict throws tool.error.

Common situations: Fresh machine with Node not on PATH (or only a runtime without npx); a stripped container image; npx shadowed by a shell alias/function that doesn't forward; corporate PATH misconfiguration.

Related errors

• git not found. Install git and retry to add AI coding skills
• CUDA execution provider not available. Use --device cpu or i
• ffmpeg and ffprobe are required. Install: ${getFFmpegInstall
• This FFmpeg build has neither libx264 nor VideoToolbox H.264
• This composition declares data-requires-webgpu, but browser

AI-assisted analysis of heygen-com/hyperframes@c2996c8626 (2026-08-12). Data as JSON: /api/errors/28ae90e4e975f452. Report an issue: GitHub.