heygen-com/hyperframes · error · Error

[lambda] SAM template not found at ${candidate}. If you're r

Error message

[lambda] SAM template not found at ${candidate}. If you're running from an installed package, point --sam-template at your local copy of examples/aws-lambda/template.yaml.

What it means

Thrown by locateSamTemplate() in packages/cli/src/commands/lambda/sam.ts:68. The Lambda deploy path expects `examples/aws-lambda/template.yaml` to exist under repoRoot. It checks that single candidate with existsSync and throws if absent. This is the dev-checkout layout; installed npm packages don't ship the examples tree, so the flag --sam-template is the documented escape hatch.

Source

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

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

/**
 * Resolve the SAM template path relative to `repoRoot`. We look for the
 * `examples/aws-lambda/template.yaml` first (development checkout) and
 * fall back to the installed-package layout when running from a globally
 * installed `hyperframes` CLI.
 */
export function locateSamTemplate(repoRoot: string): string {
  const candidate = join(repoRoot, "examples", "aws-lambda", "template.yaml");
  if (!existsSync(candidate)) {
    throw new Error(
      `[lambda] SAM template not found at ${candidate}. ` +
        `If you're running from an installed package, point --sam-template at your local copy of examples/aws-lambda/template.yaml.`,
    );
  }
  return candidate;
}

/** Run `sam deploy` non-interactively. Returns when SAM exits 0; throws on non-zero. */
export function samDeploy(opts: DeployOptions): void {
  assertSamAvailable();
  const paramOverrides = [
    `ChromeSource=${opts.chromeSource ?? "sparticuz"}`,
    `ReservedConcurrency=${opts.reservedConcurrency ?? -1}`,
  ];
  if (opts.lambdaMemoryMb !== undefined) {
    paramOverrides.push(`LambdaMemoryMb=${opts.lambdaMemoryMb}`);
  }
  const args = [

View on GitHub (pinned to c2996c8626)

Solutions

If you have the source repo, point --repo-root (or cwd) at the checkout root so examples/aws-lambda/template.yaml resolves.
If running from an installed package, copy examples/aws-lambda/template.yaml out of the repo and pass its path via --sam-template.
Verify the file actually exists: `ls examples/aws-lambda/template.yaml` from the directory you pass as repo root.
Reinstall/refresh the package if you expected the template to ship and it's missing.

Example fix

# before (installed package, template missing)
hyperframes lambda deploy --repo-root .
# after
hyperframes lambda deploy --sam-template /abs/path/to/template.yaml

Defensive patterns

Strategy: validation

Validate before calling

import { existsSync } from 'node:fs';
import { join } from 'node:path';

function resolveSamTemplate(repoRoot: string, override?: string): string {
  const path = override ?? join(repoRoot, 'examples', 'aws-lambda', 'template.yaml');
  if (!existsSync(path)) {
    throw new Error(`Template not found: ${path}. Pass --sam-template <path>.`);
  }
  return path;
}

Try / catch

try {
  locateSamTemplate(repoRoot);
} catch (error) {
  if (/SAM template not found/.test(String(error))) {
    // fall back to an explicit --sam-template arg the user supplied
    locateSamTemplate(explicitTemplatePath);
  } else throw error;
}

Prevention

Always pass --sam-template explicitly when running from an installed package.
In CI, check out the HyperFrames repo or vendor the template file alongside your deploy script.
Assert the template file exists in a preflight step before invoking deploy.

When it happens

Trigger: Calling samDeploy/locateSamTemplate with a repoRoot that does not contain examples/aws-lambda/template.yaml — most often running from a globally installed `hyperframes` CLI, from inside node_modules, or with --repo-root pointed at the wrong directory.

Common situations: Global `hyperframes` install (no examples dir in package output); running the CLI from a project that isn't the HyperFrames repo checkout; template deleted or moved; wrong --repo-root value.

Related errors

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