heygen-com/hyperframes · error · Error

`aws` CLI not found on PATH. Install from https://docs.aws.a

Error message

`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.

What it means

Thrown by assertAwsCliAvailable() in packages/cli/src/commands/lambda/sam.ts:37. HyperFrames' Lambda deploy/destroy path shells out to the AWS CLI v2 (for `aws cloudformation describe-stacks`) instead of using the SDK, so it hard-requires the `aws` binary on PATH. The guard runs `aws --version` with stdio ignored and throws this if that spawn fails (ENOENT or non-zero).

Source

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

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. */
  repoRoot: string;
  /** CloudFormation stack name. */
  stackName: string;
  region: string;
  awsProfile?: string;
  reservedConcurrency?: number;
  /** Lambda memory in MB. Forwarded as the `LambdaMemoryMb` parameter override. */
  lambdaMemoryMb?: number;
  chromeSource?: "sparticuz" | "chrome-headless-shell";
  /** Pass-through stdio. Defaults to "inherit" so SAM's progress lines stream live. */
  stdio?: "inherit" | "pipe";

View on GitHub (pinned to c2996c8626)

Solutions

Install AWS CLI v2 from the URL in the message and run `aws --version` to confirm it resolves on PATH.
If already installed, add its bin directory to PATH in the shell profile you actually launch `hyperframes` from, then open a new shell.
Run `aws configure` (or set AWS_PROFILE / AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY) so credentials exist before retrying.
In CI, use an image that ships `aws` (e.g. `amazon/aws-cli`) or add an install step before the deploy step.

Example fix

// before
hyperframes lambda deploy
// after (bash)
brew install --cask awscli   # or: pipx install awscli
aws --version                # confirm
aws configure                # set region + credentials
hyperframes lambda deploy

Defensive patterns

Strategy: validation

Validate before calling

import { execFileSync } from 'node:child_process';

function awsCliAvailable(): boolean {
  try {
    execFileSync('aws', ['--version'], { stdio: 'ignore' });
    return true;
  } catch {
    return false;
  }
}

if (!awsCliAvailable()) {
  console.error('Install AWS CLI v2 and run `aws configure` first.');
  process.exit(1);
}

Try / catch

try {
  await deployLambda(opts);
} catch (error) {
  if (/`aws` CLI not found on PATH/.test(String(error))) {
    // surface install instructions, don't retry until PATH is fixed
    throw new Error('AWS CLI missing — install from the URL in the message, then rerun.');
  }
  throw error;
}

Prevention

Add an `aws --version` check to your deploy script's preflight before invoking `hyperframes lambda deploy`.
Pin a CI image that ships aws-cli (e.g. amazon/aws-cli) so PATH is always correct.
Document the AWS CLI as a hard prerequisite in the deploy runbook, not an optional one.

When it happens

Trigger: Invoking `hyperframes lambda deploy` (which calls fetchStackOutputs -> assertAwsCliAvailable), or any code path that calls fetchStackOutputs/assertAwsCliAvailable on a machine where `aws --version` cannot be spawned.

Common situations: Fresh dev machine or CI image without AWS CLI v2 installed; AWS CLI installed via pip (v1) or under a non-default bin dir not on PATH; shells (nvm/asdf/fish) where PATH differs from the install location; logged-in user differs from the one that owns the CLI install.

Related errors

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