heygen-com/hyperframes · error · Error

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

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.

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)

Solutions

Install AWS SAM CLI from the URL in the message (https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html).
Verify the install: `sam --version` should succeed in the same shell you run HyperFrames from.
If SAM is installed but not on PATH, add its bin directory to PATH, or invoke HyperFrames from a shell that has it.
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

Defensive patterns

Strategy: validation

Validate before calling

// 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 / catch

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
  }
}

Prevention

Add AWS SAM CLI to the base CI/Docker image that runs deploys.
Run `sam --version` as a preflight check in deploy pipelines.
Ensure PATH is exported into the shell invoking HyperFrames.

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

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