{"record":{"id":"5c2d31992e13c046","repo":"heygen-com/hyperframes","slug":"getrenderprogress-executionarn-is-required","errorCode":null,"errorMessage":"[getRenderProgress] executionArn is required","messagePattern":"\\[getRenderProgress\\] executionArn is required","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/aws-lambda/src/sdk/getRenderProgress.ts","lineNumber":93,"sourceCode":"  totalFrames: number | null;\n  /** Total Lambda invocations scheduled so far (both optimized + raw task integrations). */\n  lambdasInvoked: number;\n  costs: RenderCost;\n  /** Final output object if Assemble succeeded; `null` otherwise. */\n  outputFile: { s3Uri: string; bytes: number | null } | null;\n  errors: RenderError[];\n  /** `true` once the execution has terminated in a non-`SUCCEEDED` state. */\n  fatalErrorEncountered: boolean;\n  startedAt: string;\n  endedAt: string | null;\n}\n\nconst DEFAULT_MEMORY_MB = 10240;\n\n/** Pull a current progress snapshot for one render. */\nexport async function getRenderProgress(opts: GetRenderProgressOptions): Promise<RenderProgress> {\n  if (!opts.executionArn) {\n    throw new Error(\"[getRenderProgress] executionArn is required\");\n  }\n  const sfn = opts.sfn ?? new SFNClient({ region: opts.region });\n  const memoryMb = opts.defaultMemorySizeMb ?? DEFAULT_MEMORY_MB;\n\n  const describe = await sfn.send(\n    new DescribeExecutionCommand({ executionArn: opts.executionArn }),\n  );\n  const status = (describe.status ?? \"RUNNING\") as RenderStatus;\n  const startedAt = describe.startDate?.toISOString() ?? new Date(0).toISOString();\n  const endedAt = describe.stopDate?.toISOString() ?? null;\n\n  const history = await loadFullHistory(sfn, opts.executionArn);\n  const summary = summarizeHistory(history, memoryMb);\n\n  const costs = computeRenderCost(summary.lambdaInvocations, summary.stateTransitions);\n  const overallProgress = computeOverallProgress({\n    status,\n    totalFrames: summary.totalFrames,","sourceCodeStart":75,"sourceCodeEnd":111,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/aws-lambda/src/sdk/getRenderProgress.ts#L75-L111","documentation":"Thrown by getRenderProgress when opts.executionArn is falsy. executionArn is the full Step Functions execution ARN returned by renderToLambda's RenderHandle; it is required for both DescribeExecution and the execution-history pagination. Without it the SDK call would fail with a generic validation error, so this surfaces the missing-field cause directly.","triggerScenarios":"Calling getRenderProgress without threading executionArn from the RenderHandle returned by renderToLambda; passing a renderId (the short name) instead of the full execution ARN; passing undefined when the render hasn't started yet.","commonSituations":"Confusing renderId (hf-render-<uuid>) with executionArn (arn:aws:states:…:execution:<smArn>:<name>); storing only the render name in a queue and losing the ARN; polling before renderToLambda resolved.","solutions":["Thread the full executionArn from renderToLambda's RenderHandle into getRenderProgress.","If you only have renderId + stateMachineArn, reconstruct the ARN: `${stateMachineArn.replace(':stateMachine:', ':execution:')}:${renderId}`."],"exampleFix":"// before\nconst progress = await getRenderProgress({ executionArn: handle.renderId, region });\n\n// after\nconst progress = await getRenderProgress({ executionArn: handle.executionArn, region });","handlingStrategy":"validation","validationCode":"function assertExecutionArn(value: string | undefined): asserts value is string {\n  if (!value || !value.includes(':execution:')) {\n    throw new Error('executionArn must be a full Step Functions execution ARN');\n  }\n}","typeGuard":"const isExecutionArn = (v: unknown): v is string =>\n  typeof v === 'string' && v.startsWith('arn:') && v.includes(':execution:');","tryCatchPattern":null,"preventionTips":["Thread executionArn (not renderId) from RenderHandle into getRenderProgress.","Store the full execution ARN in your queue/DB, not just the short name.","If reconstructing from renderId + stateMachineArn, build arn = smArn.replace(':stateMachine:', ':execution:') + ':' + renderId."],"tags":["step-functions","validation","render","aws-lambda"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}