Sync: Add pause/unpause functionality for sync uploads

[gavande1]

Related issues

• Fixes STU-1143

Proposed Changes

• Add pause/resume buttons for TUS uploads during sync
• Add manual pause state separate from network pause
• Rename sync-upload-paused to sync-upload-network-paused for clarity
• Add pause/play icon components
• Update UI to show info icon with tooltip when manually paused

Testing Instructions

• Checkout this branch
• Run npm start
• Connect a site to sync if not already connected
• Start a sync push operation
• Click pause button during upload phase
• Verify upload pauses and shows resume button
• Click resume to continue upload
• Verify upload resumes from where it left off

CleanShot.2026-01-12.at.17.02.49.mp4

[wpmobilebot]

📊 Performance Test Results

Comparing 27bfbe8 vs trunk

site-editor

Metric	trunk	27bfbe8	Diff	Change
load	2861.00 ms	2865.00 ms	+4.00 ms	🔴 0.1%

site-startup

Metric	trunk	27bfbe8	Diff	Change
siteCreation	7099.00 ms	8058.00 ms	+959.00 ms	🔴 13.5%
siteStartup	3925.00 ms	3929.00 ms	+4.00 ms	🔴 0.1%

---

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change

[ivan-ottinger]

This a great! Thanks for adding the Pause/Play button to the sync process, Rahul.

The changes look good to me and they work as expected. 👍🏼

I left couple comments on things I noticed.

---

When clicking the Play/Pause button, the progress jumps a bit. Maybe we could consider adjusting the logic to prevent that behavior.

[ivan-ottinger]

Actually, I noticed one issue: Sometimes, when pausing and resuming the upload, the operation fails with the following error:

[2026-01-13T15:02:32.232Z][info][main] Database export saved to /var/folders/p1/f6m7sk7948g6zj6plt84p13m0000gn/T/studio_exportUyHKOg
[2026-01-13T15:02:38.132Z][info][main] Backup created at: /var/folders/p1/f6m7sk7948g6zj6plt84p13m0000gn/T/com.wordpress.studio/site_ff7be311-4557-4a5d-bfff-99b997aee54c.tar.gz
[2026-01-13T15:02:40.655Z][erro][main] Error occurred in handler for 'pushArchive': Error: Upload completed but required header not found
    at Object.onSuccess (/Users/ivanottinger/a8c/studio/dist/main/index.js:6468:18)
    at Upload._emitSuccess (/Users/ivanottinger/a8c/studio/node_modules/tus-js-client/lib.es5/upload.js:989:22)
    at /Users/ivanottinger/a8c/studio/node_modules/tus-js-client/lib.es5/upload.js:1158:20
    at process.processTicksAndRejections (node:internal/process/task_queues:105:5)

[katinthehatsite]

I got the same error as Ivan:

Error occurred in handler for 'pushArchive': Error: Upload completed but required header not found
at Object.onSuccess (/Users/katerynakodonenko/Documents/A8C-Projects/studio/studio/dist/main/index.js:6468:18)
at Upload._emitSuccess (/Users/katerynakodonenko/Documents/A8C-Projects/studio/studio/node_modules/tus-js-client/lib.es5/upload.js:989:22)
at /Users/katerynakodonenko/Documents/A8C-Projects/studio/studio/node_modules/tus-js-client/lib.es5/upload.js:1158:20
at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
Sentry Logger [log]: Captured error event Error invoking remote method 'pushArchive': Error: Upload completed but required header not found

[katinthehatsite]

Thanks for adding these changes, this will be a great improvement for the users!

I found one edge case where I seem to be getting errors:

• Start push process on a site
• Pause an upload
• Cancel the upload
• Start again the push process for the same site
• Wait until the upload can be paused
• Pause the upload
• Observe that this throws an error:

This is the details that are captured to Sentry:

Sentry Logger [log]: Captured error event `Error invoking remote method 'pushArchive': reply was never sent`

[gavande1]

Thanks @ivan-ottinger and @katinthehatsite for noticing this error and reporting them. I have fixed the issue with the cancel push operation. It should also fix the issues you reported earlier. It would great if you could give another review. 🙂

[katinthehatsite]

Thanks @ivan-ottinger and @katinthehatsite for noticing this error and reporting them. I have fixed the issue with the cancel push operation. It should also fix the issues you reported earlier. It would great if you could give another review. 🙂

Nice, I am not seeing these errors anymore 👍 Functionality-wise, everything looked good to me. I will review the code a bit closer tomorrow morning with fresh eyes

[ivan-ottinger]

Thanks @ivan-ottinger and @katinthehatsite for noticing this error and reporting them. I have fixed the issue with the cancel push operation. It should also fix the issues you reported earlier. It would great if you could give another review. 🙂

Thank you for the updates, Rahul. I am still getting error when pausing and resuming, but different one this time:

Database export saved to /var/folders/p1/f6m7sk7948g6zj6plt84p13m0000gn/T/studio_exportw5IZUQ
Backup created at: /var/folders/p1/f6m7sk7948g6zj6plt84p13m0000gn/T/com.wordpress.studio/site_fdf6ffd0-6b85-4a3e-82ec-20e6d70b250e.tar.gz
Database export saved to /var/folders/p1/f6m7sk7948g6zj6plt84p13m0000gn/T/studio_export6HODEZ
Backup created at: /var/folders/p1/f6m7sk7948g6zj6plt84p13m0000gn/T/com.wordpress.studio/site_fdf6ffd0-6b85-4a3e-82ec-20e6d70b250e.tar.gz
Sentry Logger [log]: Captured error event `Object captured as exception with keys: error, success`
Sentry Logger [error]: Transport disabled

[katinthehatsite]

It is looking good overall on my end, I left some minor comments for consideration.

[wojtekn]

Feature-wise looks good, but I think we should adjust the design before we merge:

• icons style doesn't match the X icon, as they are thicker
• bar width and text position shouldn't change when icons appear

[gavande1]

icons style doesn't match the X icon, as they are thicker
bar width and text position shouldn't change when icons appear

Thanks, Wojtek, for raising this. These were my concerns as well. I am waiting for a response from @Marinatsu on design feedback.

Edit: I have updated the pause icon to match style of X icon from WordPress icons. I added that in 9be6d83.

[gavande1]

Thank you for the updates, Rahul. I am still getting error when pausing and resuming, but different one this time:

Database export saved to /var/folders/p1/f6m7sk7948g6zj6plt84p13m0000gn/T/studio_exportw5IZUQ
Backup created at: /var/folders/p1/f6m7sk7948g6zj6plt84p13m0000gn/T/com.wordpress.studio/site_fdf6ffd0-6b85-4a3e-82ec-20e6d70b250e.tar.gz
Database export saved to /var/folders/p1/f6m7sk7948g6zj6plt84p13m0000gn/T/studio_export6HODEZ
Backup created at: /var/folders/p1/f6m7sk7948g6zj6plt84p13m0000gn/T/com.wordpress.studio/site_fdf6ffd0-6b85-4a3e-82ec-20e6d70b250e.tar.gz
Sentry Logger [log]: Captured error event `Object captured as exception with keys: error, success`
Sentry Logger [error]: Transport disabled

Thanks @ivan-ottinger. I couldn't reproduce the error. But I tried to fix the issue in b6b2040. Can you give a quick test?

[katinthehatsite]

I found one more interesting case while testing:

• Connect two sites to a Studio site
• Start Push process on the connected site A and pause the upload
• Start Push process on the connected site B
• Unpause the uploads
• Observe the Studio site pushing the changes to two sites at once:

I also noticed an error in Sentry for this case:

Backup created at: /var/folders/bj/1qgxs1qd6_z20tw9llkw842h0000gn/T/com.wordpress.studio/site_d354f946-9026-4a52-a2ff-cd3ac7c2d172.tar.gz
Backup created at: /var/folders/bj/1qgxs1qd6_z20tw9llkw842h0000gn/T/com.wordpress.studio/site_d354f946-9026-4a52-a2ff-cd3ac7c2d172.tar.gz
Sentry Logger [log]: Captured error event `ENOENT: no such file or directory, unlink '/var/folders/bj/1qgxs1qd6_z20tw9llkw842h0000gn/T/com.wordpress.studio/site_d354f946-9026-4a52-a2ff-cd3ac7c2d172.tar.gz'`

I know that we are currently blocking the UI for pushing and pulling more than to one site at a time so I am wondering if we might want to stay consistent here as well:

In terms of functinality, with this edge case, the push worked for one site and for the other one, it sort of got stuck and it is still pending for me. I will update this comment if it goes through but I think it is probably related to the error I saw in Sentry.

[katinthehatsite]

I noticed that the sizing of the icons is different and I could see that difference visually, not a huge one. What do you think about making it consistent?

[gavande1]

Fixed in 9892f91

[ivan-ottinger]

Thanks @ivan-ottinger. I couldn't reproduce the error. But I tried to fix the issue in b6b2040. Can you give a quick test?

I have run multiple tests and spotted that the issue happens only when we pause at 100% of the upload progress. Since by then the upload is finished, I think we can hide the Pause button at that point, which should resolve the issue.

CleanShot.2026-01-16.at.11.06.54.mp4

[gavande1]

@ivan-ottinger Thanks for your suggestion. I have applied your suggestion in 2ec6e22.

[ivan-ottinger]

@ivan-ottinger Thanks for your suggestion. I have applied your suggestion in 2ec6e22.

Thanks for the update, Rahul! The change there looks good and I can confirm it fixes the issue. I did not observe any other edge cases and pausing / resuming works great. 👍🏼

I understand there might still be a design adjustment related to the buttons coming, but I am already approving the PR in case we would like to merge it in its current state.

---

Btw, I have tested on a rebased branch with latest trunk locally, just did not push it remotely.

[gavande1]

I understand there might still be a design adjustment related to the buttons coming, but I am already approving the PR in case we would like to merge it in its current state.

Tbh, I am not happy with the layout shift it does when the Play/Pause button appears and hides. It definitely needs some better UX in IHMO. cc @Marinatsu 🙂

[crisbusquets]

Hi!

I reviewed the last video shared.

There are two moments where we have odd layout shifts:

1. The one @gavande1 described above.
2. When the icons disappear to make room for the "Error pushing changes".

I see two potential solutions:

1. Add an easy-in-out transition so everything looks smoother, and it's clear that it transitions from one state to the other
2. We can also define a fixed width for that, so it doesn't change its size when there's the X and then ▶️, or when it gets replaced with the Clear option when there's an error.

[wojtekn]

Thanks for looking into this @crisbusquets

We can also define a fixed width for that, so it doesn't change its size when there's the X and then ▶️, or when it gets replaced with the Clear option when there's an error.

I think this is the simplest path forward and would result in good UX without any animated or non-animated layout shifts.

[crisbusquets]

Great! Feel free to ping me when you have a preview 🙏

[epeicher]

I have applied the suggestions as part of a7ad509 and cb53da0 and this is the result:

CleanShot.2026-01-27.at.11.59.16.mp4

@crisbusquets, please let me know any comments

[crisbusquets]

Thank you, @epeicher! I have a few comments:

The play/pause interaction feels much better now 🎉

There's a tiny layout shift we show the Push complete text. I guess it's because the icons have a different height than this text. If you share all the SVGs with me, and the height it should have, I can adjust them. The pause icon seems to have a slightly different height than the X, I can fix that too.

I don't know if this a known issue, but the right side of this section has more margin than the left side, which makes it look unpolished:

[epeicher]

Thanks for the feedback @crisbusquets! I think the issue here is the progress bar taking up the same space at the bottom. Please see the screenshots with the height. The icons can be found here for the pause icon and here for the play icon, both have a height of 20 pixels. I updated a bit the pause icon to move it down, but I agree it can be further aligned.

Paused	Push complete

The right margin is an existing issue, but I can fix it as part of these changes 👍

Please let me know how to address the layout shift with the Push complete. I believe a fixed height of 25 could resolve the issue. Additionally, I welcome any other feedback 😄

[epeicher]

Hi @crisbusquets, I have addressed your feedback as part of the latest commits, now the Pull complete message has a bigger height so there is no vertical layout shift. Also, I have reduced the padding for the controls to align them accordingly. Please find a video below. You can fast forward to the end to see the change.

CleanShot.2026-01-27.at.14.05.58.mp4

This shows the alignment of the buttons:

[crisbusquets]

Awesome, thank you! 💎 I don't see the issue with the icons now, we can ship this. I'll let you know if I see something else when I use it for my sites.