Skip to main content

Troubleshoot the blob size limit error

The BlobSizeLimitError is an error that occurs when the size of a blob (payloads including Workflow context and each Workflow and Activity argument and return value) exceeds the set limit in Temporal.

  • The max payload for a single request is 2 MB.
  • The max size limit for any given Event History transaction is 4 MB.

Why does this error occur?​

This error occurs when the size of the blob exceeds the maximum size allowed by Temporal.

This limit helps ensure that the Temporal Service prevents excessive resource usage and potential performance issues when handling large payloads.

How do I resolve this error?​

To resolve this error, reduce the size of the blob so that it is within the 4 MB limit.

There are multiple strategies you can use to avoid this error:

  1. Use compression with a custom payload codec for large payloads.

    • This addresses the immediate issue of the blob size limit; however, if blob sizes continue to grow this problem can arise again.

  2. Break larger batches of commands into smaller batch sizes:

    • Workflow-level batching:
      1. Modify the Workflow to process Activities or Child Workflows into smaller batches.
      2. Iterate through each batch, waiting for completion before moving to the next.
    • Workflow Task-level batching:
      1. Execute Activities in smaller batches within a single Workflow Task.
      2. Introduce brief pauses or sleeps (for example, 1ms) between batches.

  3. Consider offloading large payloads to an object store to reduce the risk of exceeding blob size limits:

    1. Pass references to the stored payloads within the Workflow instead of the actual data.
    2. Retrieve the payloads from the object store when needed during execution.

Workflow termination due to oversized response​

When a Workflow Task response exceeds the 4 MB gRPC message size limit, Temporal automatically terminates the Workflow Execution. This is a non-recoverable error. The Workflow can't progress if it generates a response that's too large, so retrying won't help.

This typically happens when a Workflow schedules too many Activities, Child Workflows, or other commands in a single Workflow Task. The total size of all commands generated by the Workflow Task must fit within the 4 MB limit.

If your Workflow was terminated for this reason, you'll see a WorkflowExecutionTerminated event in the Event History with the cause WORKFLOW_TASK_FAILED_CAUSE_GRPC_MESSAGE_TOO_LARGE.

To prevent this, use the batching strategies described above to split work across multiple Workflow Tasks instead of scheduling everything at once.

See the gRPC Message Too Large error reference for more details.