{"record":{"id":"99030e14fda70580","repo":"heygen-com/hyperframes","slug":"rendertolambda-statemachinearn-is-required","errorCode":null,"errorMessage":"[renderToLambda] stateMachineArn is required","messagePattern":"\\[renderToLambda\\] stateMachineArn is required","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/aws-lambda/src/sdk/renderToLambda.ts","lineNumber":89,"sourceCode":"  renderId: string;\n  /** Full execution ARN; pass to {@link getRenderProgress}. */\n  executionArn: string;\n  bucketName: string;\n  stateMachineArn: string;\n  outputS3Uri: string;\n  projectS3Uri: string;\n  startedAt: string;\n}\n\n// fallow-ignore-next-line complexity\nexport async function renderToLambda(opts: RenderToLambdaOptions): Promise<RenderHandle> {\n  validateDistributedRenderConfig(opts.config);\n\n  if (!opts.bucketName) {\n    throw new Error(\"[renderToLambda] bucketName is required\");\n  }\n  if (!opts.stateMachineArn) {\n    throw new Error(\"[renderToLambda] stateMachineArn is required\");\n  }\n  if (!opts.siteHandle && !opts.projectDir) {\n    throw new Error(\"[renderToLambda] either siteHandle or projectDir must be supplied\");\n  }\n\n  const executionName = opts.executionName ?? `hf-render-${randomUUID()}`;\n  const ext = formatExtension(opts.config.format);\n  const outputKey = opts.outputKey ?? `renders/${executionName}/output${ext}`;\n  const planOutputS3Prefix = formatS3Uri({\n    bucket: opts.bucketName,\n    key: `renders/${executionName}/`,\n  });\n  const outputS3Uri = formatS3Uri({ bucket: opts.bucketName, key: outputKey });\n\n  const site =\n    opts.siteHandle ??\n    (await deploySite({\n      projectDir: opts.projectDir as string,","sourceCodeStart":71,"sourceCodeEnd":107,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/aws-lambda/src/sdk/renderToLambda.ts#L71-L107","documentation":"Thrown by renderToLambda when opts.stateMachineArn is empty/falsy. The state machine ARN (from the SAM/CDK stack output RenderStateMachineArn) is the target of StartExecution; without it the Step Functions call would fail with a malformed-ARN error. The check is the second of three required-field guards (after bucketName, before the siteHandle/projectDir check).","triggerScenarios":"Stack output not read or mis-named; env var unset; the field is undefined because the caller built the options object conditionally and the ARN branch wasn't taken.","commonSituations":"SAM stack outputs read into a map keyed by a name that changed across versions; CDK construct renamed the output; passing executionArn (per-execution) instead of stateMachineArn (per-stack).","solutions":["Read RenderStateMachineArn from the deployed stack outputs and pass it verbatim.","Verify the ARN contains ':stateMachine:' (not ':execution:') — execution ARNs belong to a specific run.","Assert non-empty before the call.","If constructing the ARN manually, confirm region + account + machine name are correct."],"exampleFix":"// before\nawait renderToLambda({ config, bucketName, stateMachineArn: process.env.HF_EXEC_ARN });\n// wrong env var -> empty\n\n// after\nawait renderToLambda({ config, bucketName, stateMachineArn: process.env.HF_STATE_MACHINE_ARN });","handlingStrategy":"validation","validationCode":"function assertStateMachineArn(value: string | undefined): asserts value is string {\n  if (!value) throw new Error('stateMachineArn is required');\n  if (!value.includes(':stateMachine:')) throw new Error('expected a stateMachine ARN, got: ' + value);\n}","typeGuard":"const isStateMachineArn = (v: unknown): v is string =>\n  typeof v === 'string' && v.startsWith('arn:aws:states:') && v.includes(':stateMachine:');","tryCatchPattern":null,"preventionTips":["Read RenderStateMachineArn from stack outputs and pass it verbatim.","Verify the ARN contains ':stateMachine:' (not ':execution:').","Store stack outputs in a typed config object loaded at startup."],"tags":["step-functions","validation","render","aws-lambda","config"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}