What Are the Best Steps to Troubleshoot Errors With My WooCommerce Site?
Disruptions to your WooCommerce site may cause problems with Autoship Scheduled Orders or display issues on your site's pages.
Troubleshooting issues with WooCommerce sites can be tricky, so we put this helpful guide together in order to share the process that our team uses to safely & quickly troubleshoot most of the errors that we encounter when merchants are having difficulty with their WooCommerce site.
Following these troubleshooting steps will equip you to safely identify, troubleshoot and resolve errors yourself and greatly improve the speed, safety & effectiveness of troubleshooting with our own support team or others!
- Check the Autoship Cloud Error Log
- Enable Your Site Error Log
- Create A Staging Site
- Duplicating the Problem
- Deactivate Plugins
- Switch to a Basic Theme
- Advanced Troubleshooting
Setting Up for Safe and Secure Troubleshooting
1. Check the Autoship Cloud Error Log
The Autoship Cloud powered by QPilot plugin features automatic error logging for both the Autoship Cloud plugin (site errors) and API requests made by your connected QPilot Site (integration errors). You can learn more about API request errors here: WooCommerce API Healthiness.
To locate the Autoship Cloud error log, visit WP-Admin > Autoship Cloud > Settings >> Logs (tab).
Downloading the log file specific to the day you are troubleshooting enables a focused view of both errors specific to your site and your site's integration for that day. This helps troubleshooting errors not only be more efficient, but more user friendly.
2. Enable WordPress Site Error Log
Enabling your site's WordPress Debug Log will provide visibility to errors your site is experiencing while duplicating the issue and troubleshooting.
If you've never enabled your site's error log before, you may want to check out this article (by WP-Beginner) How to Set Up Error Logs.
Below is an example of the code you would add to your wp-config.php file in order to enable Error Logs:
// 'true' enables debug mode on your site define( 'WP_DEBUG', true ); // 'true' writes any errors to your error log define( 'WP_DEBUG_LOG', true ); // set this to false to prevent debug messages from displaying on your site define( 'WP_DEBUG_DISPLAY', false );
Your site's error log is usually found within the wp-content directory.
Referencing the time stamps and file sources related to each error can help to pinpoint when and why the error occurred, so it's a good idea to review the error log each time you test and duplicate an issue.
3. Create a Staging Site
Why create a staging site?
In short, staging sites are a copy (or very close duplicate) of your live/production WordPress site where changes can be safely tested without impacting your live/production site.
- For example, some troubleshooting steps will change how your site displays pages to users, so having a separate site to test with and troubleshoot safely prevents your site visitors and customers from being exposed to your troubleshooting efforts.
- Many issues with WordPress and WooCommerce Sites will result in the support team requesting access to a staging site, so having one set up will save you time, and speed up the overall troubleshooting process.
If you do not know how to create a staging site, your hosting provider will likely be able to assist you.
Pro Tip! If you are going to connect your staging site to your QPilot Account, you will also want to ensure that your staging site is not restricted and can successfully connect to QPilot.
Safe and Secure Troubleshooting
4. Duplicating the Problem
With error logging enabled for your staging site, you can now safely duplicate the problem you are experiencing.
Duplicating (or "recreating") the problem gives a "baseline" of comparison and helps maintain focus throughout troubleshooting steps. If you're unable to duplicate the problem on your staging site, you'll want to compare the staging site with your production/live site to understand the difference.
Whether the problem you are experiencing is with a page display, an API integration issue, or a checkout issue, duplicating the problem and then reviewing the site's error log can provide detailed information regarding why the error is occurring.
As a general practice, you should attempt to duplicate the problem before and after each troubleshooting step to see if each change removes the problem and use this process of elimination to narrow down the cause of the issue.
5. Deactivate Plugins
Plugins introduce custom code to your WooCommerce Site, so the next step in narrowing down the cause of the issue is deactivate all "non-essential" plugins and attempt to duplicate the problem.
"Non-essential" simply means that these plugins are not part of the solution or functionality that you are troubleshooting, so when looking into an issue that's impacting Autoship Cloud, the only plugins that should remain activated are WooCommerce and Autoship Cloud powered by QPilot.
In some cases, like testing the WooCommerce Checkout for example, you'll need to leave your payment gateway plugin activated.
If you are testing checkout, you should see if your payment gateway plugin enables you to switch your settings to "Sandbox" or "Test" settings to avoid needing to refund charges to an actual credit card.
Was the problem duplicated?
If not, congratulations! You have discovered the issue to be with one of the plugins that you deactivated.
Reactivate your plugins one by one and try to duplicate the issue; once you are able to duplicate the issue again, you will want to take note of which plugin causes the issue and contact the plugin's author, explain the issue and include any related events from your site's error log.
Is the issue still happening?
If the issue is still happening with all of your plugins deactivated, check your error log to see if any new entries appeared and continue to the next troubleshooting step.
6. Switch to a "Basic" Theme
Themes also can introduce custom code to your WooCommerce site. Activating a "basic" theme on your staging site (for example: Storefront) will help to identify if the theme that was Active before is causing the issue.
In your staging site, visit WP-Admin > Appearance > Themes to activate a basic theme. After switching themes, attempt to duplicate the problem.
Was the problem duplicated?
If not, and changing to a basic theme resolves the issue, then the problem is either caused by the theme itself or by custom code added to the theme's files.
You will want to contact the person that added the custom code or the theme author, provide them with your site's error log and ask them to help you resolve the problem.
Still Experiencing Problems?
If you have performed all of the steps above and the problem still persists, then the issue goes beyond your WooCommerce Site's Theme and Plugins and more advanced troubleshooting is needed.
Who usually helps with advanced troubleshooting?
- Your site's developer
- Your WordPress hosting provider
- WooCommerce support
- Additionally, you can contact our dev support (email@example.com), where we can help you troubleshoot with advanced diagnostics.
Requesting help from Support? Here is what to include!
All of the steps previously performed are valuable for advanced troubleshooting, so use this process to provide important information to our support or whomever you are seeking help from:
- A brief explanation of your issue and troubleshooting steps
- Your site's Autoship Cloud and WordPress Debug error log
- Your staging site's URL
- Your WooCommerce System Status Report
- WP-Admin access to your staging site (username and password)
- FTP or SFTP Credentials to your staging site (can be provided by your WordPress hosting provider if you don't know how to provide FTP access)
Advanced troubleshooting is needed when problems go beyond your WooCommerce Site's Theme and Plugins.
For example, your WordPress site may experience issues with:
- Site configuration (memory, redirects)
- Firewalls (Can I Whitelist QPilot IP Addresses?)
- WooCommerce REST API Requests (GET / POST / PUT / DELETE)
- File Permissions
- Database Issues
If you are experiencing site slowdowns or timeout, you may want to check your site memory and WP-Cron status. For example, you can adjust your site's configuration to increase performance by changing the memory limit within the wp-config.php file:
Additionally, you may try disabling WP-Cron. WP-Cron can sometimes slowdown sites with higher traffic (including API requests to create Autoship Orders). This can be done by adding the following to your wp-config.php file:
WooCommerce REST API Testing and Troubleshooting
Autoship Cloud powered by QPilot integrates with your online store's WooCommerce REST API to synchronize data, display embedded reporting & hosted apps, and create & update Autoship Orders in WooCommerce.
For Autoship Cloud to function properly, your site must be able to handle basic WooCommerce REST API requests successfully.
Using Autoship Cloud to test your site's WooCommerce REST API
The Autoship Cloud powered by QPilot plugin enables you to run a quick test to see if your WooCommerce REST API is functional.
- Visit WP-Admin > Autoship Cloud > Settings
- Select "Test Integration" and view the result in the API Health Status Check
For most WooCommerce sites, this "API Health Check" is a sufficient test.
However, this quick test is not a replacement for testing Scheduled Orders. If your site is experiencing REST API issues, but your API Health Status Check appears "healthy", then please move to "Testing the WooCommerce REST API without Autoship Cloud" (below).
Testing the WooCommerce REST API without Autoship Cloud
Autoship Cloud works by integrating with your site's WooCommerce REST API, but that does not mean that you need the Autoship Cloud plugin in order to test and troubleshoot issues with the WooCommerce REST API.
WooCommerce documents how to test & troubleshoot the WooCommerce REST API, with or without the Autoship Cloud plugin activated. To see these steps, visit their documentation here: Getting Started with the WooCommerce REST API.
Below are specific sections within WooCommerce's REST API "Getting Started" documentation that are helpful to focus on for testing & troubleshooting:
- Making a Basic (API) Request
- WooCommerce shows how to test a basic API request using a free client (like Postman)
- Server Does Not Support POST / DELETE / PUT
- WooCommerce offers a solution for site's hosted on servers that do not support all API Request methods. If your hosting provider does not enable your site's WooCommerce REST API to work with GET, POST and PUT requests, then you will need to request that they update these permissions for you.
- Pro Tip! When requesting support from your hosting provider regarding the WooCommerce REST API, ensure that the focus is on enabling basic WooCommerce REST API requests, so that your hosting provider knows that these basic requests need to succeed (even when the Autoship Cloud plugin is deactivated or not installed).
- Once your site's WooCommerce REST API is successfully responding to GET, POST and PUT requests, then Autoship Cloud powered by QPilot's integration should work as expected!