{"record":{"id":"40e7e4d4e1ea3c17","repo":"heygen-com/hyperframes","slug":"sam-cli-not-found-on-path-install-aws-sam-cli-f","errorCode":null,"errorMessage":"`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.","messagePattern":"`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\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/lambda/sam.ts","lineNumber":30,"sourceCode":" *      shouldn't have to maintain it twice.\n *   3. SAM's `--resolve-s3` auto-creates an artifact bucket for the\n *      handler ZIP upload, which we'd otherwise have to re-implement.\n *\n * CDK adopters use `HyperframesRenderStack` directly from their own\n * CDK app — this CLI path is for users who don't want to write a CDK\n * project.\n */\n\nimport { execFileSync, spawnSync } from \"node:child_process\";\nimport { existsSync } from \"node:fs\";\nimport { 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. */","sourceCodeStart":12,"sourceCodeEnd":48,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/commands/lambda/sam.ts#L12-L48","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nhyperframes lambda deploy  # sam not installed\n# after\n# install SAM CLI per the docs, verify, then\nsam --version && hyperframes lambda deploy","handlingStrategy":"validation","validationCode":"// Confirm SAM CLI is on PATH before invoking lambda deploy/destroy\nimport { spawnSync } from \"node:child_process\";\nfunction assertSamOnPath(): void {\n  if (spawnSync(\"sam\", [\"--version\"], { stdio: \"ignore\" }).status !== 0) {\n    throw new Error(\"Install AWS SAM CLI before running lambda deploy\");\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  await runDeploy({ /* ... */ });\n} catch (err) {\n  if (/`sam` CLI not found on PATH/.test((err as Error).message))) {\n    // install SAM CLI per the linked docs, then retry\n  }\n}","preventionTips":["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."],"tags":["cli","lambda","deploy","aws-sam","environment","path","prerequisite"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}