{"record":{"id":"9c3c60a978dfe17e","repo":"heygen-com/hyperframes","slug":"aws-cli-not-found-on-path-install-from-https","errorCode":null,"errorMessage":"`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.","messagePattern":"`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\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/lambda/sam.ts","lineNumber":41,"sourceCode":"import { join } from \"node:path\";\n\n/** Throws with a clear hint when the SAM CLI is not on PATH. */\nfunction assertSamAvailable(): void {\n  try {\n    execFileSync(\"sam\", [\"--version\"], { stdio: \"ignore\" });\n  } catch {\n    throw new Error(\n      \"`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.\",\n    );\n  }\n}\n\n/** Throws with a clear hint when the `aws` CLI is not on PATH. */\nfunction assertAwsCliAvailable(): void {\n  try {\n    execFileSync(\"aws\", [\"--version\"], { stdio: \"ignore\" });\n  } catch {\n    throw new Error(\n      \"`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.\",\n    );\n  }\n}\n\nexport interface DeployOptions {\n  /** Repository root — the SAM template lives at `examples/aws-lambda/template.yaml` underneath. */\n  repoRoot: string;\n  /** CloudFormation stack name. */\n  stackName: string;\n  region: string;\n  awsProfile?: string;\n  reservedConcurrency?: number;\n  /** Lambda memory in MB. Forwarded as the `LambdaMemoryMb` parameter override. */\n  lambdaMemoryMb?: number;\n  chromeSource?: \"sparticuz\" | \"chrome-headless-shell\";\n  /** Pass-through stdio. Defaults to \"inherit\" so SAM's progress lines stream live. */\n  stdio?: \"inherit\" | \"pipe\";","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/commands/lambda/sam.ts#L23-L59","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nhyperframes lambda deploy\n// after (bash)\nbrew install --cask awscli   # or: pipx install awscli\naws --version                # confirm\naws configure                # set region + credentials\nhyperframes lambda deploy","handlingStrategy":"validation","validationCode":"import { execFileSync } from 'node:child_process';\n\nfunction awsCliAvailable(): boolean {\n  try {\n    execFileSync('aws', ['--version'], { stdio: 'ignore' });\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nif (!awsCliAvailable()) {\n  console.error('Install AWS CLI v2 and run `aws configure` first.');\n  process.exit(1);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await deployLambda(opts);\n} catch (error) {\n  if (/`aws` CLI not found on PATH/.test(String(error))) {\n    // surface install instructions, don't retry until PATH is fixed\n    throw new Error('AWS CLI missing — install from the URL in the message, then rerun.');\n  }\n  throw error;\n}","preventionTips":["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."],"tags":["aws","cli","environment","lambda","deployment"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}