heygen-com/hyperframes · error

[renderToLambda] StartExecution returned no executionArn

Error message

[renderToLambda] StartExecution returned no executionArn

What it means

Thrown by renderToLambda after a successful StartExecutionCommand when the SDK response object has no executionArn field. Under normal operation the AWS Step Functions API always returns the execution ARN on a 200 response, so in production this indicates a transport/SDK anomaly or a non-conformant SFN-compatible service. The most common real-world trigger is a test stub or mock SFN client whose send() return value omits the field.

Source

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

  // (typically from `config.variables` containing inlined media) surfaces
  // as `States.DataLimitExceeded` 50 ms into the execution, far from the
  // caller's stack frame. Measured AFTER `deploySite` so the synthesised
  // `ProjectS3Uri` is counted (a few hundred bytes either way, but the
  // check should be against the actual wire payload).
  validateStepFunctionsInputSize(input);

  const sfn = opts.sfn ?? new SFNClient({ region: opts.region });
  const startedAt = new Date().toISOString();
  const response = await sfn.send(
    new StartExecutionCommand({
      stateMachineArn: opts.stateMachineArn,
      name: executionName,
      input: JSON.stringify(input),
    }),
  );

  if (!response.executionArn) {
    throw new Error("[renderToLambda] StartExecution returned no executionArn");
  }

  return {
    renderId: executionName,
    executionArn: response.executionArn,
    bucketName: opts.bucketName,
    stateMachineArn: opts.stateMachineArn,
    outputS3Uri,
    projectS3Uri: site.projectS3Uri,
    startedAt,
  };
}

View on GitHub (pinned to c2996c8626)

Solutions

1. In tests, ensure the mock SFN client returns { executionArn: 'arn:…:execution:…' }.
2. Verify the @aws-sdk/client-sfn version matches the one the package was built against.
3. If using LocalStack, upgrade to an image that supports the executionArn response field.
4. Log the raw response object to confirm which field is missing.

Example fix

// before (test mock)
sfn.send = async () => ({ $metadata: { httpStatusCode: 200 } });

// after
sfn.send = async () => ({
  executionArn: `arn:aws:states:us-east-1:000000000000:execution:sm:hf-render-test`,
  startDate: new Date(),
});

const hasExecutionArn = (r: unknown): r is { executionArn: string } =>
  typeof (r as any)?.executionArn === 'string';

const response = await sfn.send(new StartExecutionCommand({ … }));
if (!response.executionArn) {
  throw new Error('StartExecution returned no executionArn; check SDK/SFN compatibility');
}

When it happens

Trigger: A unit/integration test injects opts.sfn as a fake client whose send() resolves to {} or { $metadata: … } without executionArn. In production: an SDK version regression, a proxy that strips fields, or a Step Functions-compatible engine (LocalStack, a third-party runtime) that doesn't populate executionArn.

Common situations: Test mocks that return a partial StartExecution response; running against LocalStack with an older image; a custom SFN-compatible backend; an SDK middleware that accidentally drops the field.

Related errors

• [getRenderProgress] executionArn is required
• [renderToLambda] stateMachineArn is required
• [renderToLambda] bucketName is required
• [renderToLambda] either siteHandle or projectDir must be sup
• [validateConfig] config: Step Functions execution input is $

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