heygen-com/hyperframes · error · Error

`sam` CLI not found on PATH. Install AWS SAM CLI from…

Error message

`sam` CLI not found on PATH. Install AWS SAM CLI from https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html and retry.

What it means

Thrown by assertSamAvailable when `sam --version` cannot be executed (execFileSync throws). AWS SAM CLI is a hard prerequisite for `lambda deploy` and `lambda destroy` because the CLI shells out to `sam deploy` for CloudFormation/SAM stack management. The message points at the official install URL so the user can remediate in one step.

Solutions

1. Install AWS SAM CLI from the URL in the message (https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html).
2. Verify the install: `sam --version` should succeed in the same shell you run HyperFrames from.
3. If SAM is installed but not on PATH, add its bin directory to PATH, or invoke HyperFrames from a shell that has it.
4. In CI, add the SAM CLI setup step before the deploy step.

Example fix

# before
hyperframes lambda deploy  # sam not installed
# after
# install SAM CLI per the docs, verify, then
sam --version && hyperframes lambda deploy

// Confirm SAM CLI is on PATH before invoking lambda deploy/destroy
import { spawnSync } from "node:child_process";
function assertSamOnPath(): void {
  if (spawnSync("sam", ["--version"], { stdio: "ignore" }).status !== 0) {
    throw new Error("Install AWS SAM CLI before running lambda deploy");
  }
}

try {
  await runDeploy({ /* ... */ });
} catch (err) {
  if (/`sam` CLI not found on PATH/.test((err as Error).message))) {
    // install SAM CLI per the linked docs, then retry
  }
}

When it happens

Trigger: Running `hyperframes lambda deploy` (or `destroy`) on a machine where the AWS SAM CLI is not installed, not on PATH, or the `sam` binary isn't executable.

Common situations: Fresh CI runner without SAM CLI preinstalled; a Docker image that omits it; SAM installed under a different name (e.g. `sam-cli`); PATH not exported into the shell running HyperFrames.

Related errors

• [hyperframes lambda] could not find the repo root (no…
• `aws` CLI not found on PATH. Install from…
• Could not extract a frame from video
• [lambda deploy] handler ZIP build exited with code
• --skip-build set but

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

Appendix: source

Thrown at packages/cli/src/commands/lambda/sam.ts:30

 *      shouldn't have to maintain it twice.
 *   3. SAM's `--resolve-s3` auto-creates an artifact bucket for the
 *      handler ZIP upload, which we'd otherwise have to re-implement.
 *
 * CDK adopters use `HyperframesRenderStack` directly from their own
 * CDK app — this CLI path is for users who don't want to write a CDK
 * project.
 */

import { execFileSync, spawnSync } from "node:child_process";
import { existsSync } from "node:fs";
import { join } from "node:path";

/** Throws with a clear hint when the SAM CLI is not on PATH. */
function assertSamAvailable(): void {
  try {
    execFileSync("sam", ["--version"], { stdio: "ignore" });
  } catch {
    throw new Error(
      "`sam` CLI not found on PATH. Install AWS SAM CLI from https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html and retry.",
    );
  }
}

/** Throws with a clear hint when the `aws` CLI is not on PATH. */
function assertAwsCliAvailable(): void {
  try {
    execFileSync("aws", ["--version"], { stdio: "ignore" });
  } catch {
    throw new Error(
      "`aws` CLI not found on PATH. Install from https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html and configure credentials before retrying.",
    );
  }
}

export interface DeployOptions {
  /** Repository root — the SAM template lives at `examples/aws-lambda/template.yaml` underneath. */

View on GitHub (pinned to c2996c8626)