heygen-com/hyperframes · error · Error

[lambda] sam deploy exited with code ${result.status ?? "unk

Error message

[lambda] sam deploy exited with code ${result.status ?? "unknown"}\nIf a prior attempt left a stack in ROLLBACK_COMPLETE, CloudFormation can't reuse it. Delete it before retrying:\n  aws cloudformation delete-stack --stack-name aws-sam-cli-managed-default --region ${opts.region}\n  aws cloudformation delete-stack --stack-name ${opts.stackName} --region ${opts.region}\n(the first is SAM's managed artifacts stack from --resolve-s3; the second is the render stack).

What it means

Thrown by samDeploy() in packages/cli/src/commands/lambda/sam.ts:108 after `sam deploy` (spawnSync) exits non-zero. HyperFrames runs SAM non-interactively with --resolve-s3, --no-confirm-changeset, --no-fail-on-empty-changeset, so a non-zero exit is a real failure. The message specifically calls out ROLLBACK_COMPLETE: a prior failed deploy leaves the CloudFormation stack in a state where it cannot be updated, only deleted and recreated.

Source

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

    "--stack-name",
    opts.stackName,
    "--region",
    opts.region,
    "--resolve-s3",
    "--capabilities",
    "CAPABILITY_IAM",
    "--no-confirm-changeset",
    "--no-fail-on-empty-changeset",
    "--parameter-overrides",
    ...paramOverrides,
  ];
  if (opts.awsProfile) {
    args.push("--profile", opts.awsProfile);
  }
  const samDir = join(opts.repoRoot, "examples", "aws-lambda");
  const result = spawnSync("sam", args, { cwd: samDir, stdio: opts.stdio ?? "inherit" });
  if (result.status !== 0) {
    throw new Error(
      `[lambda] sam deploy exited with code ${result.status ?? "unknown"}\n` +
        `If a prior attempt left a stack in ROLLBACK_COMPLETE, CloudFormation can't reuse it. ` +
        `Delete it before retrying:\n` +
        `  aws cloudformation delete-stack --stack-name aws-sam-cli-managed-default --region ${opts.region}\n` +
        `  aws cloudformation delete-stack --stack-name ${opts.stackName} --region ${opts.region}\n` +
        `(the first is SAM's managed artifacts stack from --resolve-s3; the second is the render stack).`,
    );
  }
}

/** Run `sam delete` non-interactively. */
export function samDelete(opts: {
  repoRoot: string;
  stackName: string;
  region: string;
  awsProfile?: string;
  stdio?: "inherit" | "pipe";
}): void {

View on GitHub (pinned to c2996c8626)

Solutions

Read the SAM stderr/stdout above the error — the real CloudFormation failure reason is streamed there (this message only wraps the exit code).
If the stack is in ROLLBACK_COMPLETE, run the two `aws cloudformation delete-stack` commands printed in the message, wait for DELETE_COMPLETE, then retry.
Verify the AWS profile/region have permission to create IAM roles, S3 buckets, Lambda, and Step Functions.
Confirm parameter overrides are valid for the template (e.g. chromeSource is 'sparticuz' or 'chrome-headless-shell').

Example fix

# before
hyperframes lambda deploy   # exits non-zero
# after
aws cloudformation delete-stack --stack-name aws-sam-cli-managed-default --region us-east-1
aws cloudformation delete-stack --stack-name <stackName> --region us-east-1
# wait for DELETE_COMPLETE, then
hyperframes lambda deploy

Defensive patterns

Strategy: try-catch

Validate before calling

import { execFileSync } from 'node:child_process';

function stackIsRollbackComplete(name: string, region: string): boolean {
  try {
    const out = execFileSync('aws', [
      'cloudformation', 'describe-stacks', '--stack-name', name,
      '--region', region, '--query', 'Stacks[0].StackStatus', '--output', 'text',
    ], { encoding: 'utf-8' }).trim();
    return out === 'ROLLBACK_COMPLETE';
  } catch {
    return false;
  }
}

Try / catch

try {
  samDeploy(opts);
} catch (error) {
  if (/ROLLBACK_COMPLETE/.test(String(error))) {
    // delete both stacks as the message instructs, wait for DELETE_COMPLETE, then retry once
    await deleteStuckStacks(opts);
    samDeploy(opts);
  } else {
    throw error;
  }
}

Prevention

Stream SAM stderr to logs so the wrapped exit code has the real CF reason next to it.
Before deploy, check the stack status; if ROLLBACK_COMPLETE, delete it programmatically first.
Verify IAM permissions and parameter overrides in a dry validation step (sam validate / cfn-lint) before the real deploy.
Use --no-fail-on-empty-changeset (already set) so idempotent re-deploys don't trip this.

When it happens

Trigger: samDeploy where the underlying `sam deploy` exits != 0: insufficient IAM perms, a stack stuck in ROLLBACK_COMPLETE from a prior attempt, region/profile mismatch, invalid parameter overrides (ChromeSource/ReservedConcurrency/LambdaMemoryMb), missing managed-artifacts bucket, or template syntax errors.

Common situations: First deploy failed (e.g. quota/perm) and left the stack in ROLLBACK_COMPLETE; wrong --region or --aws-profile; CAPABILITY_IAM not granted; SAM CLI version that needs different flags; conflicting resources already in AWS.

Related errors

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