Fix upload hang when converting long animated GIFs: decode only the first frame for still outputs

[adamsilverstein]

What?

Fixes #80259.

Uploading a long animated GIF with client-side media processing enabled hung forever: endless spinner, upload never completing, no console errors. Any GIF whose frame count × frame height exceeds 65,500 px triggered the hang - easy to hit with screen recordings (the reported sample is a 2.2 MB, 769-frame GIF).

Why?

After a successful GIF → video conversion, a static first-frame poster is sideloaded as a companion (animated_video_poster). Generating that poster runs convertImageFormat (GIF → JPEG) in @wordpress/vips, which loaded animation-capable inputs with [n=-1] (all frames) regardless of the output format. libvips represents an all-frames load as one vertical strip frames × height pixels tall - 1517 × 657,495 px for the reported sample.

Saving that strip as JPEG fails (libjpeg's maximum image dimension is 65,500 px), and inside the image worker that failure kills a libvips worker pthread without unwinding, so the RPC call never settles. The poster sideload stays pending forever, the parent item's finalize gate never closes, and the UI spins indefinitely.

Two secondary defects compounded this:

• Even when the strip could be saved (short GIFs), the "poster" was the entire film strip rather than the first frame, contrary to the code's intent.
• If a wasm failure does surface synchronously, it throws a WebAssembly.Exception, which is not an Error and has no message. The worker RPC reply only carries the error message string, so the main thread mistook the failure for a successful undefined result instead of a rejection.

How?

• @wordpress/vips: convertImageFormat now only loads all frames when the output format also supports animation. A still output (JPEG poster) decodes just the first frame - no giant strip, correct single-frame poster, and poster generation drops from ~seconds/hang to ~0.1 s. compressImage (same input/output type) and rotateImage keep the all-frames behavior for animated formats.
• @wordpress/worker-threads: expose() now normalizes thrown values that are not Error instances (or carry an empty message) - e.g. WebAssembly.Exception, thrown strings - into an Error with a non-empty message, so every worker failure reaches the main thread as a promise rejection. Without this, such failures are indistinguishable from a successful undefined result. (Complementary to Worker threads: reject pending RPC calls on worker failure or termination #79955, which rejects pending calls when the worker itself dies.)

With the poster failure gone and failures propagating as rejections, the existing upload-queue error handling does the right thing: a failed companion sideload cancels silently and the parent GIF attachment finalizes normally (the "fall back to a regular upload" behavior).

Empirically verified in isolated browser harnesses (wasm-vips 0.0.18): first-frame load converts the previously-hanging sample in 0.1 s (1517×855, 46 KB JPEG), while the all-frames load reproducibly throws/hangs.

Testing Instructions

1. Enable client-side media processing (default) in a cross-origin-isolated environment.
2. Insert an Image block and upload a long animated GIF (sample attached to GIF to video conversion: upload hangs forever when a GIF's frames x height exceeds the JPEG dimension limit #80259, or any GIF with frames × height > 65,500, e.g. a 700-frame 100×100 GIF).
3. Before this change: the spinner never stops. After: the upload completes, the attachment carries animated_video and animated_video_poster companions, and the poster is a single frame with the GIF's dimensions.

Automated coverage:

• New e2e test completes the upload of a long animated GIF and produces a single-frame poster with a synthetic 700-frame 100×100 fixture (~97 KB). It times out on trunk (hang reproduced) and passes with this fix, including asserting the poster's dimensions.
• New unit tests: convertImageFormat frame-loading matrix (GIF→JPEG, GIF→WebP, GIF→GIF, still→still) and worker RPC error propagation (Error, non-Error, empty-message, thrown string).

npm run test:unit -- packages/vips/src/test/convert-image-format.ts packages/worker-threads/src/test/error-propagation.test.ts
npm run test:e2e -- test/e2e/specs/editor/various/gif-to-video.spec.js

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: adamsilverstein <adamsilverstein@git.wordpress.org>
Co-authored-by: andrewserong <andrewserong@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

Size Change: +493 B (+0.01%)

Total Size: 7.72 MB

📦 View Changed

Filename	Size	Change
build/modules/video-conversion/worker.min.js	83.4 kB	+192 B (+0.23%)
build/modules/vips/worker.min.js	3.69 MB	+301 B (+0.01%)

_{compressed-size-action}

[adamsilverstein]

I verified manually that this fixes uploading the Tabs-block.gif test image (although the transcode to video was a bit slow)

[github-actions]

Flaky tests detected in 5f50607.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/29466329317
📝 Reported issues:

• [Flaky Test] Should insert content using the global inserter #78924 in /test/e2e/specs/widgets/editing-widgets.spec.js

[andrewserong]

Thanks for looking into a fix! Code-wise this makes sense to me as a fix, but in practice when I attempt to upload larger GIFs they still appear to get stuck in the uploading state:

I'm attempting to upload fairly raw GIFs generated by Gifox, and they're large in both pixel dimensions and filesize (e.g. 20mb). Interestingly, Github won't let me upload either, but Github fails gracefully with an error, whereas the editor gets stuck in that loading state.

Once it's stuck in that state, subsequent uploads appear to also fail and don't trigger the uploading snackbar. And nothing gets logged to the browser console either 🤔

---

I've tested a couple more images in case it helps.

This one of Jack Nicholson appears to fail in the same way:

This one that includes transparency doesn't fail (I assume because in this case we're skipping the video conversion?)

Let me know if there's anything more I can test!

[andrewserong]

This might be a nitpicky comment, but withNormalizedErrors now creates a new object and copies keys over to it. Should we flag in the docs that this means that target must be a flat object of own methods (i.e. not a class instance where the methods from the class would be expected to be available, but won't be on a fresh object as the class methods are not exposed by Object.keys()).

I'm mostly asking this because worker-threads is a separate package, and so I wasn't sure how general purpose it's meant to be, versus our specific use case of vips.

[andrewserong]

I threw the problem I ran into at a Claude instance, and the suggestions sound valid. I think the main issue I was running into might have been that the GIFs I'm uploading are big enough that they get resized, too? Here's the notes from a Claude review:

1. Cap the animated decode in resizeImage the way the poster fix caps convertImageFormat — bound frameCount × pageHeight against the encoder/decoder limit and fall back
   to first-frame (or refuse) when it would overflow, instead of unconditionally n=-1.

2. Make a wedged worker recoverable — this is the real systemic gap. Add a per-call timeout (or re-enable a heartbeat) at the worker-threads RPC layer, and terminate + recreate the worker on timeout so one bad call can't poison the queue for everything behind it. This would have turned this entire bug into a surfaced error.

3. Pass maxDimensions to convertGifToVideo so large GIFs downscale below encoder limits rather than stalling the video path.

What do you reckon?

[adamsilverstein]

I'm attempting to upload fairly raw GIFs generated by Gifox, and they're large in both pixel dimensions and filesize (e.g. 20mb). Interestingly, Github won't let me upload either, but Github fails gracefully with an error, whereas the editor gets stuck in that loading state.

Once it's stuck in that state, subsequent uploads appear to also fail and don't trigger the uploading snackbar. And nothing gets logged to the browser console either 🤔

Thanks for the continued testing. Seems like we need to add some additional guardrails here. I'll use your test images to see if I can debug the exact point of failure further. Your suggestions sound good, I suspect we need:

• A maximum size for GIFs that will get converted (likely W x H x frames)
• A timeout: if the image isn't converted in X seconds, time out, keeping only the original upload
• Possibly better progress tracking, if we know how many frames X of Y, maybe we should expose that as a percentage somewhere?

[adamsilverstein]

This one of Jack Nicholson appears to fail in the same way:

@andrewserong GitHub converts this to a PNG from your upload, I'm not sure how to get to your original. I'll see if I can find it online. Putting images in a zip is a workaround for this issue.

[adamsilverstein]

@andrewserong I wasn't able to reproduce the failures you describe yet using the Playground link: https://playground.wordpress.net/?gutenberg-pr=80260

I tested with several very large GIFs from https://commons.wikimedia.org/wiki/Category:Animated_GIF_files_between_50_MP_and_100_MP

I got successful video conversions even for the >40MB weather animation (although it took a while).

Can you zip up and share some of your specific failing images and I will try to reproduce. Maybe something is different about them.

[adamsilverstein]

We may want to show a conversion progress indicator of some sort since this process can take quite some time and it might look like the upload has hung when in fact the conversion is still going on.

I opened a separate issue to track this: #80325

[andrewserong]

Thanks Adam, I'll re-test today to see if I can reproduce again, there's always the chance I was doing something wrong! I was testing locally, but not using Playground. I'd assumed Playground still didn't work for client-side media processing, but has that changed?

Here's a few of my GIFs as zips:

Jack Nicholson Reaction GIF.gif.zip

mild-panic-intensifies.gif.zip

2026-07-10 14.44.24.gif.zip

[andrewserong]

I'll re-test today to see if I can reproduce again

Okay, this is interesting.

The Jack Nicholson one is testing okay for me today locally, and I thought that the larger GIF was failing during upload... it turns out that it seems it's the long processing issue. I left it running in my browser, and it turns out it managed to finish eventually... after 30 minutes 😅

In case it helps: I'm running a MacBook Air, so my computer isn't the most powerful. I'm wondering if there's something a bit intermittent / particular to the resources of the user's browser when this is happening?

We may want to show a conversion progress indicator of some sort since this process can take quite some time and it might look like the upload has hung when in fact the conversion is still going on.

I wonder if it would also make sense to bail after a threshold? Once conversion takes longer than a perceived "fairly quick" amount of time, the conversion feature itself ceases to be useful. Which is to say: client-side video processing is a compelling feature and idea, but if it takes too long, I'd probably ask the question of whether or not this is worth it at all 🤔

(Not meaning to be critical of the feature, just putting myself in the shoes of the average user wondering why their upload is taking so long)

[andrewserong]

I'm also on an Air, but the latest model with maxed ram so might work better for me because of those.

I'm on an M4 Air, 32gb RAM, but when I was testing yesterday, I was also running 3x WP environments and dozens of browser tabs, so may have stretched my resources a little thin.

yes it has changed! Client-side media works in playground since

Fantastic! That's good to know and will make testing simpler 😄

possibly yes - I was thinking that as well originally.
I'm also working on a "progress bar" for the processing phase, since we know exactly how much is complete (eg. we know its X of Y frames so can show an accurate percentage or progress bar). maybe this could have an explicit cancel mechanism as well. I feel like with a solid progress indicator its fine it if takes a long time to process?

That's a good point. For me, I think it comes back to the expectation for the majority user case. If I've uploaded an image, do I expect it to handle conversion? If so (and this is an argument for your modal PR) then yes, if there's an accurate progress bar, that seems to mitigate things for me.

However, if the conversion is going to take many minutes, or in the case of the large screengrab I shared, 30 minutes, I'd say we're way past the threshold of usefulness. If it's going to take 30 minutes, there are better tools for conversion than directly in the block editor — i.e. for that case, someone should either be using a managed video service for conversion (that can happen server-side without the browser window being open) or converting themselves prior to upload.

I guess what I'm trying to say is: is there a heuristic we can use to determine "good enough" for this conversion feature so that it's active when it's most useful, but doesn't apply when things are above a threshold of some kind? I'm not too sure how we'd do this, but from the user side of things, if we can bail if the file that's being upload is beyond a threshold, I think that'd be the right way to fix it. Kind of like a soft rejection, e.g. "too big too convert, upload file as-is" or something like that 🤔

thanks for sharing those. merging for now and we can keep iterating to see if we can improve performance or UX.

Absolutely, this discussion convinces me that there's more to explore here in follow-ups. My vote would be: through this WP Beta phase, let's do what we can to make this feature feel really nice and stable, but keeping in mind that if it still feels flaky we might need to reconsider its inclusion.

Thanks for all the back and forth here!

[github-actions]

There was a conflict while trying to cherry-pick the commit to the wp/7.1 branch. Please resolve the conflict manually and create a PR to the wp/7.1 branch.

PRs to wp/7.1 are similar to PRs to trunk, but you should base your PR on the wp/7.1 branch instead of trunk.

# Checkout the wp/7.1 branch instead of trunk.
git checkout wp/7.1

# Create a new branch for your PR.
git checkout -b my-branch

# Cherry-pick the commit.
git cherry-pick ee1bdb84ebdf1e2a59bf9d63ebe07cf32e96e4ca

# Check which files have conflicts.
git status

# Resolve the conflict...
# Add the resolved files to the staging area.
git status
git add .
git cherry-pick --continue

# Push the branch to the repository
git push origin my-branch

# Create a PR and set the base to the wp/7.1 branch.
# See https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-base-branch-of-a-pull-request.

[adamsilverstein]

I cherry picked these changes in #80342

[adamsilverstein]

I wonder if it would also make sense to bail after a threshold? Once conversion takes longer than a perceived "fairly quick" amount of time, the conversion feature itself ceases to be useful.

I'm going to open an Issue/PR to add this, otherwise this feature might feel broken when users try it with very large GIFs. we can reconsider if we merge a progress bar.

For now I will silently fail only the video conversion part - falling back to the already uploaded original GIF file.

• Client-side media: add timeout and size guardrails to GIF to video conversion #80376

[adamsilverstein]

@andrewserong I testing 2026-07-10 14.44.24.gif.zip it does take an extra-ordinary amount of time to process. with the progress bar (#80325), I see all frames are processed and then the spinner continues to show uploading in progress and it goes on and on.

This image is a good candidate for further debugging, I'm not clear why its hanging, the video conversion seems to only take around 10 seconds for me locally.

[adamsilverstein]

Root-caused the hang with 2026-07-10 14.44.24.gif (2554×1676 × 800 frames = 3.4 gigapixels). The conversion itself is not the hang - three things compound after it:

1. Sub-size grind: every animated sub-size re-decodes all 800 frames in wasm-vips (~80-90 s each, more for the larger sizes), so medium_large/large/1536x1536/2048x2048 grind for tens of minutes while the snackbar shows "uploading". Fixed by Client-side media: generate animated image sub-sizes from the first frame only, matching core #80268 (first-frame sub-sizes, matching core) - with it a sub-size takes ~2 s.
2. Blocked cancellation: cancelItem awaited a cancel RPC that the busy vips worker cannot answer (it is synchronously blocked inside wasm), so cancelled items stayed in the queue and kept the parent unfinalized. Fixed in Media: Add timeout and size guardrails to client-side GIF to video conversion #80379.
3. Starved follow-up uploads: any subsequent upload's transparency check queues behind the grind in the same worker, so later uploads appear to silently do nothing - matching @andrewserong's report. Same root cause; Client-side media: generate animated image sub-sizes from the first frame only, matching core #80268 removes the grind. In one test the tab crashed outright under the load, which would explain the "nothing gets logged" case.

#80379 also adds the guardrails from #80376: this GIF now skips video conversion in ~0.1 s (11× over the new 300 MP pixel budget) with a SCRIPT_DEBUG console diagnostic, and conversions that do start are abandoned after 30 s.

[t-hamano]

This PR was backported to the wp/7.1 branch by #80342.

[jasmussen]

I wonder if it would also make sense to bail after a threshold? Once conversion takes longer than a perceived "fairly quick" amount of time, the conversion feature itself ceases to be useful. Which is to say: client-side video processing is a compelling feature and idea, but if it takes too long, I'd probably ask the question of whether or not this is worth it at all 🤔

possibly yes - I was thinking that as well originally.

It's a tricky one. We're definitely entering that space of media management for which big players in the space, like Google and Proton Drive, have a dedicated tray that sits in the bottom of the screen. Think UploadProgressSnackbar, but permanent and when you click it it opens a list of files that are being processed (uploaded, or in our case, converted). This UI affords showing contextual errors: which file failed (e.g. what happens if you upload two big GIFs in a row quickly one after another), and options to retry upload, or in our case, retry conversion. Often times there will even be an "Errors" dedicated screen with a list of which uploads failed.

We might eventually want something like this for the Media Library, which could coexist inside the editor situationally. But not today: it's a big undertaking.

So my question is: what is the simplest thing we can do? If it's to bail with a Notice suggesting you retry, perhaps that's the path forward.

[adamsilverstein]

So my question is: what is the simplest thing we can do? If it's to bail with a Notice suggesting you retry, perhaps that's the path forward.

For now, we silently fall back to the existing server upload route when the video conversion process appears to fail because it times out without completing. So the user gets what they currently get: their uploaded GIF. If SCRIPT_DEBUG is enabled an error also shows in the console, but for the average user the main side effect is they don't get the video conversion.

entering that space of media management for which big players in the space, like Google and Proton Drive

I agree and it sounds neat to incorporate some of the media library features directly into the editor. Since both will enable media uploads and a queue, it makes sense to share components and logic for things like progress indicators, batches, status, etc. I love this long term vision!

One difference for media with WordPress vs. the other systems like docs: we have our existing server processing pipeline to fall back on. This provides a reliable (battle-tested!) failsafe that while not quite as good as what client-side media enables, is still better than showing an error and blocking users.