heygen-com/hyperframes · error

[renderToLambda] bucketName is required

Error message

[renderToLambda] bucketName is required

What it means

Thrown by renderToLambda when opts.bucketName is empty/falsy. The bucket is the S3 destination for both the uploaded project tarball and the render output; every downstream URI is built from it. The check fires before any AWS call so a missing bucket surfaces at the SDK boundary rather than as an opaque S3 AccessDenied/NoSuchBucket later. bucketName normally comes from the SAM/CDK stack output RenderBucketName.

Source

Thrown at packages/aws-lambda/src/sdk/renderToLambda.ts:86

/** Stable identifier + every URL/ARN the caller needs to follow the render. */
export interface RenderHandle {
  /** Same as the Step Functions execution name. */
  renderId: string;
  /** Full execution ARN; pass to {@link getRenderProgress}. */
  executionArn: string;
  bucketName: string;
  stateMachineArn: string;
  outputS3Uri: string;
  projectS3Uri: string;
  startedAt: string;
}

// fallow-ignore-next-line complexity
export async function renderToLambda(opts: RenderToLambdaOptions): Promise<RenderHandle> {
  validateDistributedRenderConfig(opts.config);

  if (!opts.bucketName) {
    throw new Error("[renderToLambda] bucketName is required");
  }
  if (!opts.stateMachineArn) {
    throw new Error("[renderToLambda] stateMachineArn is required");
  }
  if (!opts.siteHandle && !opts.projectDir) {
    throw new Error("[renderToLambda] either siteHandle or projectDir must be supplied");
  }

  const executionName = opts.executionName ?? `hf-render-${randomUUID()}`;
  const ext = formatExtension(opts.config.format);
  const outputKey = opts.outputKey ?? `renders/${executionName}/output${ext}`;
  const planOutputS3Prefix = formatS3Uri({
    bucket: opts.bucketName,
    key: `renders/${executionName}/`,
  });
  const outputS3Uri = formatS3Uri({ bucket: opts.bucketName, key: outputKey });

  const site =

View on GitHub (pinned to c2996c8626)

Solutions

1. Confirm the SAM stack is deployed and read RenderBucketName from its outputs.
2. Assert the bucket is non-empty before calling renderToLambda: if (!bucketName) throw.
3. Check the options key spelling — it is bucketName, not bucket.
4. Log the stack outputs to verify the value is populated.

Example fix

// before
await renderToLambda({ config, bucketName: process.env.HF_BUCKET, stateMachineArn });
// HF_BUCKET unset -> empty string

// after
const bucketName = requiredEnv('HF_BUCKET');
await renderToLambda({ config, bucketName, stateMachineArn });

function assertRequiredString(value: string | undefined, field: string): asserts value is string {
  if (!value) throw new Error(`${field} is required`);
}

const isNonEmptyString = (v: unknown): v is string =>
  typeof v === 'string' && v.length > 0;

When it happens

Trigger: Caller reads the stack output into an env var that isn't set; the stack output name changed; the field is passed as undefined from a config object that wasn't populated; a typo in the options key.

Common situations: SAM/CDK stack not deployed so the output is empty; reading process.env.HF_BUCKET_NAME before it's exported; passing { bucket: … } (wrong key) instead of { bucketName: … }.

Related errors

• [renderToLambda] stateMachineArn is required
• [renderToLambda] either siteHandle or projectDir must be sup
• [getRenderProgress] executionArn is required
• [validateConfig] config: Step Functions execution input is $
• [s3Transport] expected s3:// URI, got: ${JSON.stringify(uri)

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