remotion-dev/remotion · error · RemotionException

Failed to decode Lambda response payload: {e}

Error message

Failed to decode Lambda response payload: {e}

What it means

Raised when the raw Lambda Payload bytes cannot be decoded as UTF-8 (UnicodeDecodeError). Indicates the response body contains bytes outside the UTF-8 range, which the Remotion protocol does not expect.

Source

Thrown at packages/lambda-python/remotion_lambda/remotionclient.py:495

            # boto3.client('lambda').invoke returns a dictionary.
            # 'Payload' is a StreamingBody object.
            response: Dict[str, Any] = client.invoke(FunctionName=function_name, Payload=payload)
            streaming_body: StreamingBody = response['Payload']
            result_raw = streaming_body.read().decode('utf-8')
            parsed_results = self._parse_stream(result_raw)
            decoded_result = parsed_results[-1] if parsed_results else {}
        except ClientError as e:
            raise e
        except ParamValidationError as e:
            raise RemotionInvalidArgumentException(
                f"Invalid Lambda invocation parameters: {e}"
            ) from e
        except json.JSONDecodeError as e:
            raise RemotionException(
                f"Failed to decode final Lambda response: {e}. Raw response: {result_raw}"
            ) from e
        except UnicodeDecodeError as e:
            raise RemotionException(
                f"Failed to decode Lambda response payload: {e}"
            ) from e

        if 'errorMessage' in decoded_result:
            raise RemotionRenderingOutputError(
                f"Lambda function returned an error: {decoded_result['errorMessage']}"
            )

        if 'type' in decoded_result and decoded_result['type'] == 'error':
            raise RemotionRenderingOutputError(
                f"Remotion rendering error: {decoded_result['message']}"
            )
        if 'type' not in decoded_result or decoded_result['type'] != 'success':
            raise RemotionRenderingOutputError(
                f"Unexpected Lambda response format: {result_raw}"
            )

        return decoded_result

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Inspect the UnicodeDecodeError position in __cause__ to confirm truncation vs binary content.
2. Check CloudWatch Logs for the Lambda function for crashes that produced a binary error page.
3. Retry the render; transient truncation often clears on a fresh invocation.
4. If persistently binary, capture raw bytes via the AWS CLI to confirm the function's actual output.

Example fix

// before - flaky network truncates the streaming body mid-multibyte
client.render_media(...)

# after - retry transient decode failures
from botocore.exceptions import ClientError
for attempt in range(3):
    try:
        client.render_media(...)
        break
    except UnicodeDecodeError:
        if attempt == 2: raise

for attempt in range(3):
    try:
        result = client.render_media(...)
        break
    except RemotionException as e:
        if 'Failed to decode Lambda response payload' in str(e) and attempt < 2:
            sleep(2 ** attempt)
            continue
        raise

When it happens

Trigger: Lambda returns binary data, a non-UTF-8 encoded error page, or a corrupted byte stream from a truncated response; the streaming body read() yields partial bytes due to a network drop.

Common situations: Network interruption truncating multi-byte sequences; a proxy injecting a gzip/binary error page; Lambda runtime returning an unexpected binary artifact; mismatched encoding between function and client.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Failed to decode final Lambda response: {e}. Raw response: {
• You have multiple buckets ({', '.join(buckets)}) in your S3
• Failed to parse Lambda response stream: {e}
• Lambda function returned an error: {decoded_result['errorMes
• Unexpected Lambda response format: {result_raw}

AI-assisted analysis of remotion-dev/remotion@78fe4bb3fd (2026-08-12). Data as JSON: /api/errors/8f06c9a946f02923. Report an issue: GitHub.