{"record":{"id":"ca8bafcd3be81e9a","repo":"heygen-com/hyperframes","slug":"handler-unknown-action-json-stringify-exhau","errorCode":null,"errorMessage":"[handler] unknown Action: ${JSON.stringify((_exhaustive as { Action?: string }).Action)}. Expected one of \"plan\", \"renderChunk\", \"assemble\".","messagePattern":"\\[handler\\] unknown Action: (.+?)\\)\\.Action\\)\\}\\. Expected one of \"plan\", \"renderChunk\", \"assemble\"\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/aws-lambda/src/handler.ts","lineNumber":118,"sourceCode":"  validateEventS3Uris(unwrapped);\n  primeRuntimeEnv();\n  // Single structured boot log line — CloudWatch Logs Insights queries\n  // key off `event=handler_start` to grep for a specific Action / S3 URI\n  // when triaging without attaching a debugger.\n  logEvent({ event: \"handler_start\", action: unwrapped.Action, input: summarizeEvent(unwrapped) });\n  try {\n    switch (unwrapped.Action) {\n      case \"plan\":\n        return await handlePlan(unwrapped, deps);\n      case \"renderChunk\":\n        return await handleRenderChunk(unwrapped, deps);\n      case \"assemble\":\n        return await handleAssemble(unwrapped, deps);\n      default: {\n        // Compile-time exhaustiveness: a new LambdaAction member trips\n        // the `never` assignment before the runtime error is reachable.\n        const _exhaustive: never = unwrapped;\n        throw new Error(\n          `[handler] unknown Action: ${JSON.stringify(\n            (_exhaustive as { Action?: string }).Action,\n          )}. Expected one of \"plan\", \"renderChunk\", \"assemble\".`,\n        );\n      }\n    }\n  } catch (err) {\n    normalizeTerminalErrorName(err);\n    // Log before re-throwing so CloudWatch captures the structured\n    // error context alongside Lambda's default stack trace. Otherwise\n    // ops only sees the trace and has to correlate with execution\n    // history to recover the action + input.\n    logEvent({\n      event: \"handler_error\",\n      action: unwrapped.Action,\n      input: summarizeEvent(unwrapped),\n      message: err instanceof Error ? err.message : String(err),\n      name: err instanceof Error ? err.name : undefined,","sourceCodeStart":100,"sourceCodeEnd":136,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/aws-lambda/src/handler.ts#L100-L136","documentation":"Thrown by the Lambda handler's action dispatch when the `Action` field does not match any of `plan`, `renderChunk`, `assemble`. The `default` branch assigns the event to a `never`-typed variable so a new `LambdaAction` member breaks compilation before this runtime error is reachable — it is the exhaustiveness guard for the discriminated union.","triggerScenarios":"An event reaches the dispatch switch with an `Action` value other than the three known ones — either an unknown action was sent, or a new action variant was added to the union without a handler case.","commonSituations":"Caller sends `Action: \"planV2\"` or some future action the handler doesn't yet support; a producer/CLI version skew where the client emits actions this Lambda version doesn't recognize; malformed test fixtures.","solutions":["Align caller and Lambda versions — send only `plan`, `renderChunk`, or `assemble`.","If you added a new LambdaAction variant, add its case to the switch (the `never` assignment will have already failed the build).","Inspect the `Action` value printed in the message and fix the caller's payload.","Redeploy the Lambda so its supported actions match the producer."],"exampleFix":"// before: producer emits unsupported action\n{ Action: \"planV2\", ... }\n// after\n{ Action: \"plan\", ... }","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"const LAMBDA_ACTIONS = new Set([\"plan\", \"renderChunk\", \"assemble\"]);\nfunction isLambdaAction(value: unknown): value is \"plan\" | \"renderChunk\" | \"assemble\" {\n  return typeof value === \"string\" && LAMBDA_ACTIONS.has(value);\n}","tryCatchPattern":"try {\n  return await dispatch(unwrapped, deps);\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith(\"[handler] unknown Action\")) {\n    // caller version skew — reject the payload with a 4xx-shaped error\n  }\n  throw err;\n}","preventionTips":["Keep producer and Lambda versions in lockstep; gate deploys on action-set compatibility.","Add an integration test that exercises every supported Action against the deployed Lambda.","When adding a new LambdaAction variant, rely on the `never` exhaustiveness check to force a handler case."],"tags":["handler","dispatch","typescript","exhaustiveness","lambda"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}