docs: update blob size limit error troubleshooting page

[lennessyy]

Summary

• Updates the blob size limit error troubleshooting page to recommend External Storage as the primary solution for large payloads
• Reorders resolution strategies to put External Storage first, followed by compression and batching
• Adds link to the Python SDK large payload storage guide

Split from #4333 (PR 3 of 3).

Test plan

• Verify the blob-size-limit-error.mdx page renders correctly
• Confirm links to External Storage and Python SDK pages resolve properly

🤖 Generated with Claude Code

┆Attachments: EDU-6149 docs: update blob size limit error troubleshooting page

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
temporal-documentation	Error		Apr 2, 2026 6:23pm

[github-actions]

📖 Docs PR preview links

• Troubleshooting
  • Blob size limit error

[drewhoskins-temporal]

"Recommended" is a bit strong given that it's in pre-release. But if you add a pre-release note, that could address gaps in terms of language support and stability

[lennessyy]

I'll keep this as the first item but remove (Recommended) for now. We can add it back either during Public Preview or GA

[drewhoskins-temporal]

Hmm, I know you aren't adding this, so no need to act now, but I wonder if anything about this is still accurate. If it's referring to server side errors, I think we throw GrpcMessageTooLarge in the latter case (but we can check w/ eng to be sure.) and BadAttributes in the former case. At least that's what I discussed with @simvlad and @jmaeagle99 but maybe I'm confused about what this means.

Update: according to https://github.com/search?q=org%3Atemporalio%20BlobSizeLimitError&type=code, I think "BlobSizeLimitError" is the actual size limit rather than the error that's thrown...

[simvlad]

In case if it exceeds 2MB, we terminated the workflow with one of bad** errors, like the following:

BadScheduleActivityAttributes: ScheduleActivityTaskCommandAttributes.Input exceeds size limit.

but this is specific to the large payloads in the activity input. For example, we also throw WORKFLOW_TASK_FAILED_CAUSE_BAD_UPDATE_WORKFLOW_EXECUTION_MESSAGE.

As for the GrpcMessageTooLarge, it would be on the client and look like this:

rpc error: code = ResourceExhausted desc = grpc: received message larger than max (5767664 vs. 4194304

[drewhoskins-temporal]

Suggested change

	2. Use compression with a [custom Payload Codec](/payload-codec) for large payloads. This addresses the immediate issue,
	2. Use compression with a [custom Payload Codec](/payload-codec) for large payloads. But even if this addresses the immediate issue,

[drewhoskins-temporal]

nit: "Even if your payloads are within the limit today" -- the user probably wouldn't be in this doc if that were the case. =) But I like the advice in general.

[lennessyy]

I was thinking they may have multiple Workflows. They ran into this error on one of them, but this could nudge them to refactor others even if those aren't reporting errors now.

[drewhoskins-temporal]

I think it's too early to wipe the old advice. (a) cos pre-release/limited language support, (b) since we don't provide the ability to create payload handles yet, the advice to "Pass references to the stored payloads within the Workflow instead of the actual data." is still valid no matter what.

Maybe we just list these as alternatives?

[simvlad]

Actually, I tried it again. In the case workflow task response exceeds 4MB gRPC limit, the workflow would keep retrying with:

{
  "cause": "WORKFLOW_TASK_FAILED_CAUSE_GRPC_MESSAGE_TOO_LARGE",
  "failure": {
    "message": "rpc error: code = ResourceExhausted desc = grpc: received message larger than max (5243837 vs. 4194304)",
    "applicationFailureInfo": {
      "type": "GrpcMessageTooLargeError"
    }
  }
}

So this is not correct