heygen-com/hyperframes · error · InvalidConfigError

[validateConfig] config: Step Functions execution input is $

Error message

[validateConfig] config: Step Functions execution input is ${byteLength} bytes, which exceeds the ${MAX_STEP_FUNCTIONS_INPUT_BYTES}-byte (256 KiB) limit for Standard workflows. Variables are for typed data (strings, numbers, structured records); media assets (images, audio, video) should be passed as URL references the composition resolves at render time, not inlined as base64. See ${LARGE_VARIABLES_DOCS_URL} for the URL-your-assets convention.

What it means

Thrown as an InvalidConfigError by validateStepFunctionsInputSize when the UTF-8 byte length of the serialized Step Functions execution input exceeds 256 KiB (MAX_STEP_FUNCTIONS_INPUT_BYTES = 262144). Step Functions Standard workflows hard-cap execution input at 256 KiB; without this check the oversized payload would start the execution and fail ~50ms in with States.DataLimitExceeded, far from the caller's stack. The message names the actual byte count, the cap, and points to the docs convention of passing media as URL references instead of inlined base64.

Source

Thrown at packages/aws-lambda/src/sdk/validateConfig.ts:69

  let serialized: string | undefined;
  try {
    serialized = JSON.stringify(input);
  } catch (err) {
    throw new InvalidConfigError(
      "config",
      `Step Functions execution input is not JSON-serializable: ${err instanceof Error ? err.message : String(err)}`,
    );
  }
  if (serialized === undefined) {
    throw new InvalidConfigError(
      "config",
      "Step Functions execution input is not JSON-serializable (JSON.stringify returned undefined). " +
        "Check that all fields, including config.variables, are plain JSON values.",
    );
  }
  const byteLength = Buffer.byteLength(serialized, "utf8");
  if (byteLength > MAX_STEP_FUNCTIONS_INPUT_BYTES) {
    throw new InvalidConfigError(
      "config",
      `Step Functions execution input is ${byteLength} bytes, which exceeds the ` +
        `${MAX_STEP_FUNCTIONS_INPUT_BYTES}-byte (256 KiB) limit for Standard workflows. ` +
        `Variables are for typed data (strings, numbers, structured records); media assets ` +
        `(images, audio, video) should be passed as URL references the composition resolves ` +
        `at render time, not inlined as base64. See ${LARGE_VARIABLES_DOCS_URL} for the ` +
        `URL-your-assets convention.`,
    );
  }
}

View on GitHub (pinned to c2996c8626)

Solutions

1. Move inlined media (images/audio/video) out of variables and pass them as URLs the composition resolves at render time.
2. Upload large data blobs to S3 and pass the object URL in variables instead of the bytes.
3. Trim or paginate large data structures; pre-aggregate on the client.
4. Run Buffer.byteLength(JSON.stringify(input), 'utf8') locally to see how close you are to 262144.

Example fix

// before
config.variables = { logo: 'data:image/png;base64,iVBOR...' }; // ~200 KB

// after
config.variables = { logoUrl: 'https://cdn.example.com/logo.png' };
// composition resolves logoUrl at render time

const MAX = 256 * 1024;
function assertUnderSfnLimit(input: unknown): void {
  const bytes = Buffer.byteLength(JSON.stringify(input), 'utf8');
  if (bytes > MAX) throw new Error(`input ${bytes}B exceeds ${MAX}B; inline media as URLs`);
}

When it happens

Trigger: config.variables contains one or more base64-encoded media assets (images, short audio clips) inlined directly; a very large JSON structure (deeply nested data); many large string values. The whole input (including ProjectS3Uri, OutputS3Uri, Config) is measured.

Common situations: Inlining a logo PNG as base64 in variables; embedding a subtitle/caption blob; a data-viz payload with thousands of points; passing an entire HTML composition string inline instead of via the project tarball.

Related errors

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

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