diff --git a/docs/references/errors.mdx b/docs/references/errors.mdx index a09abef6f9..2e886d719b 100644 --- a/docs/references/errors.mdx +++ b/docs/references/errors.mdx @@ -192,6 +192,18 @@ A retry will be scheduled if the error is recoverable. {/* TODO: more info */} +## gRPC Message Too Large {#grpc-message-too-large} + +This error occurs when the Workflow Task response exceeds the gRPC message size limit of 4 MB. +The Workflow Execution is automatically terminated because this is a non-recoverable error. + +This typically happens when a Workflow schedules too many Activities, Child Workflows, or commands in a single Workflow Task, or when a Workflow returns a large result. + +To resolve this error, fix your Workflow code and start a new Workflow Execution. +Break work into smaller batches, reduce the size of Workflow returns, use Continue-As-New for long-running Workflows, or compress large payloads with a custom Payload Codec. + +See the [BlobSizeLimitError troubleshooting guide](/troubleshooting/blob-size-limit-error) for detailed resolution strategies. + ## Nondeterminism Error {#non-deterministic-error} The [Workflow Task](/tasks#workflow-task) failed due to a [nondeterminism error](/workflow-definition#non-deterministic-change). diff --git a/docs/troubleshooting/blob-size-limit-error.mdx b/docs/troubleshooting/blob-size-limit-error.mdx index a2c0c2949d..f8c66473eb 100644 --- a/docs/troubleshooting/blob-size-limit-error.mdx +++ b/docs/troubleshooting/blob-size-limit-error.mdx @@ -45,3 +45,15 @@ There are multiple strategies you can use to avoid this error: 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](/references/errors#grpc-message-too-large) for more details.