Automattic / Automattic/jetpack
Enhancement for features that rely on the Jetpack connection: proactively notify users when the connection is broken
- Dominant language
- PHP
- Stars
- 1.8k
- Forks
- 898
- Avg merge
- 1d 18h
- Merged PRs (30d)
- 774
Description
### Impacted plugin
Jetpack, Backup, Search, Social, VideoPress
### What
Many Jetpack features, like Social, VideoPress, and others, rely on a stable connection to WordPress.com. You can check out the full list of features that need this connection here: https://jetpack.com/support/why-the-wordpress-com-connection-is-important-for-jetpack/#jetpack-features-that-need-a-wordpress-com-account-connection
Right now, when the connection is broken, we only surface the issue by showing a `Missing site connection` message in My Jetpack:

This is great and helpful, but it doesn’t cover situations where the connection looks fine but is actually broken. When that happens, users only find out there’s an issue after something goes wrong, often leading to frustration.
### How
We need to let users know if their connection is broken before they try to do something that relies on it. That way, they can fix it first and avoid unnecessary headaches.
Here are a few recent instances where users could have had a better experience if they had been informed about their broken Jetpack connection:
- **Jetpack Social:** If the connection is broken and the user publishes a post expecting it to auto-share to their social accounts, nothing happens. They don’t realize the issue until they contact support to figure out what went wrong.
- p1735570967548839-slack-C0CMN0V97 - a T51 partner had issues with Bluesky connections, only realizing the connection was broken after publishing a post and noticing it wasn't shared to Bluesky.
- **VideoPress:** If the connection isn’t working, uploading videos fails—but the user isn’t told why, which leaves them guessing.
- In 9146085-zd-a8c, the user ultimately canceled their subscription. This was previously reported on Slack p1725368863355259-slack-C02LT75D3, and a task was created for VideoPress at that time, here: https://github.com/Automattic/videopress/issues/1117
These are just two examples, but the impact applies to any feature that depends on the connection.
Proactively informing users about a broken connection would greatly enhance their experience and prevent unexpected issues. The implementation can vary depending on the product or feature and its technical feasibility.
For instance, we could create a notification similar to the one shown in the screenshot for disconnected accounts, or opt for a targeted approach.
For example, if a user with a broken Jetpack connection attempts to upload a video, we could display an error message explaining the issue. This message could include a link to the Jetpack Debugger page, which provides troubleshooting steps and helpful suggestions to resolve the problem.
Contributor guide
Research direction
No source files or tests are named. Start by reviewing the existing “Missing site connection” handling in My Jetpack and the Jetpack Debugger entry point, then identify how the impacted features detect a broken connection; done means a defined, testable notification or feature-specific error path for the affected cases.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php
- Domain
- authentication, backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100