Jetpack can do a lot for a WordPress website.
Backups. Security. Statistics. Performance features. Connections to WordPress.com.
But when that connection gets sick, Jetpack has a habit of presenting symptoms without making the underlying diagnosis immediately obvious.
Before you start deactivating plugins, changing firewall settings, reinstalling WordPress, or blaming your hosting company, there’s a much easier place to start: Jetpack Debug.
The Diagnosis: Jetpack Isn’t Talking to Your Website
A surprising number of Jetpack problems aren’t really problems with the feature you’re trying to use.
They’re communication problems.
Jetpack needs to be able to communicate between your WordPress website and WordPress.com. When something interrupts that conversation, seemingly unrelated Jetpack features can begin behaving strangely.
The Jetpack Debug tool is essentially a quick medical exam for that connection.
Enter your website address and let it run its tests.
Jetpack’s own support documentation recommends the tool for identifying connection problems.
Symptoms That May Send You to the Debugger
You might want to give your website a Jetpack checkup if you’re seeing things such as:
- Jetpack refusing to connect
- Features suddenly stopping
- Backup or Scan connection problems
- XML-RPC errors
- Connection timeouts
- HTTP errors
- WordPress.com saying it cannot communicate with your site
- Jetpack behaving normally one day and irrationally the next
Think of these as symptoms.
The Debug tool helps you get closer to the actual disease.
How to Use Jetpack Debug
Fortunately, this examination doesn’t require a white coat.
Go to https://jptools.wordpress.com/debug/
Enter the full address of your WordPress website and run the test.
If your site is associated with your WordPress.com account, the tool may also allow you to select it directly. If it isn’t listed, you can simply enter the URL manually.
If the connection passes its tests, Jetpack says you should receive an indication that everything looks good.
If it doesn’t?
Now you have something useful to work with.
Common Diagnosis: XML-RPC Trouble
One of the important pieces of the Jetpack connection is WordPress’s xmlrpc.php file.
Jetpack uses it to communicate with your website.
If your hosting company, security plugin, firewall, CDN, or another system blocks that communication, Jetpack may develop a serious case of Communication Anxiety Disorder.
Jetpack recommends checking your XML-RPC endpoint when troubleshooting connection problems. A normal WordPress installation should respond to a browser request for xmlrpc.php with a message indicating that the XML-RPC server accepts POST requests only.
A 404, 403, or other unexpected response can point you toward the real problem.
Another Common Diagnosis: An Overprotective Firewall
Security is good.
A firewall that protects your website is good.
A firewall that protects your website so enthusiastically that legitimate services can no longer reach it is less good.
Jetpack specifically notes that a firewall, web application firewall, hosting rule, or security plugin can block WordPress.com requests to xmlrpc.php.
In other words, your website may be suffering from Security Trust Issues.
The site has become suspicious of everyone — including Jetpack.
The prescription may involve adjusting the security rule rather than changing Jetpack itself.
HTTP Errors Are Clues, Not Just Bad News
The debugger may also return familiar HTTP status codes such as:
400, 401, 403, 404, 408, 429, 500, 502, 503, or 504.
Don’t treat the number as meaningless technical gibberish.
It’s a clue.
Jetpack maintains guidance explaining what these HTTP responses can mean when its service is attempting to communicate with WordPress.
For example, a 500 error points you in a very different direction from a 403 error.
One suggests the server itself is having trouble completing the request.
The other may suggest that the request is being forbidden.
Same patient. Different diagnosis. Different treatment.
Cloudflare Can Occasionally Complicate the Conversation
Cloudflare and other content delivery or security services can add another layer between Jetpack and your WordPress installation.
That layer is usually helpful.
Sometimes it gets a little too involved in the relationship.
Jetpack documents cases where sites using Cloudflare or other proxy services can encounter connection problems, including XML-RPC-related errors.
If Jetpack Debug points toward that part of your configuration, investigate the proxy or firewall rules before performing major surgery on WordPress.
The Prescription: Diagnose Before You Start Changing Things
This is the part we really like about Jetpack Debug.
It encourages the correct troubleshooting order.
Test first. Change things second.
Far too many WordPress troubleshooting sessions begin like this:
Deactivate something.
Refresh.
Change something else.
Refresh.
Clear every cache known to mankind.
Refresh.
Reinstall something.
Refresh.
Forget what you changed three steps ago.
Now the website has three new problems and nobody remembers what the original problem was.
That’s not debugging.
That’s exploratory surgery.
A diagnostic tool gives you evidence before you begin treatment.
If Jetpack Debug Finds a Problem
Once the debugger gives you an error, use that error to narrow the investigation.
Depending on the diagnosis, the treatment might involve checking:
- Your Jetpack connection
xmlrpc.php- Your hosting firewall
- A WordPress security plugin
- Cloudflare or another CDN
- SSL/HTTPS configuration
- Plugin conflicts
- Theme conflicts
- Server configuration
- PHP errors
- WordPress Site Health
Jetpack’s current troubleshooting documentation covers these areas in considerably more detail.
The important point is that you now have a direction.
Don’t Immediately Reconnect Jetpack for Every Problem
This is worth mentioning.
Disconnecting and reconnecting Jetpack can help with some connection problems, and Jetpack provides a procedure for doing so. But reconnecting isn’t a universal cure.
For example, if a firewall is actively blocking WordPress.com from reaching your site, reconnecting Jetpack doesn’t remove the firewall rule. Jetpack specifically recommends investigating the block instead.
Treat the disease, not merely the symptom.
Your website will appreciate it.
Our Prescription
If Jetpack starts acting strangely, resist the urge to start randomly changing settings.
Visit https://jptools.wordpress.com/debug/
Run the test.
Read the diagnosis.
Then start troubleshooting.
It takes only a moment, costs nothing, and may save you from an afternoon of unnecessarily performing open-heart surgery on a perfectly innocent WordPress installation.
Sometimes your website doesn’t need rebuilding.
It just needs a proper diagnosis.
