WC Studio
Academy / Troubleshooting and Maintenance

Ultimate Guide to Common WooCommerce Issues and How to Fix Them

Introduction

WooCommerce powers over 30% of all online stores, but even the most robust setups can hit snags—from fatal PHP errors to payment gateway timeouts. This guide walks through the most frequent WooCommerce headaches and gives you clear, actionable fixes. You’ll learn how to diagnose white screens, 500 errors, checkout failures, email delivery hiccups, broken images, SSL warnings, database connection problems, and more. Armed with built‑in debugging tools and best practices for maintenance, you can keep your store running smoothly and delight your customers.

 

 

Feature Snippet

Quick fixes for common WooCommerce issues:

  • Enable WP_DEBUG and inspect debug.log for PHP errors.

  • Check server error logs and .htaccess for 500 Internal Server Errors.

  • Isolate plugin or theme conflicts via a staging site and default theme.

  • Resolve checkout failures by flushing permalinks, updating SSL, and testing gateways in sandbox mode.

  • Fix email delivery with SMTP plugins (WP Mail SMTP), DNS SPF/DKIM records, and Mailgun/Postmark.

  • Repair image/library errors by resetting file permissions and regenerating thumbnails.

  • Redirect or recreate missing pages to cure 404s.

  • Harden SSL/TLS to eliminate mixed‑content warnings.

  • Verify DB credentials in wp-config.php and repair tables via phpMyAdmin or wp‑cli.

  • Use Query Monitor and Health Check plugins for ongoing maintenance and alerts.

 

 

1. White Screen of Death (PHP Errors)

Symptoms: Blank frontend or admin, no error message.
Root Causes: Fatal PHP error, memory exhaustion, incompatible PHP version.

Diagnosis

  1. Enable debugging in wp-config.php:

  2. php

  3. CopyInsert

define( 'WP_DEBUG', true );

define( 'WP_DEBUG_LOG', true );

  1. define( 'WP_DEBUG_DISPLAY', false );

  2. Reproduce the error and inspect wp-content/debug.log for fatal messages, file paths, and line numbers.

Fixes

  • Memory Limit: Increase in wp-config.php or php.ini:

  • php

  • CopyInsert

  • define( 'WP_MEMORY_LIMIT', '256M' );

  • PHP Version: Ensure your host runs PHP 8.0+ (WooCommerce 7.x+). Downgrade or upgrade code accordingly.

  • Plugin/Theme Conflict:

    1. Rename plugins/ folder to plugins-off/ to deactivate all.

    2. Rename back and activate one by one to isolate the culprit.

  • Syntax Errors: If debug log points to a custom snippet, fix the misplaced semicolon or bracket.

 

 

2. 500 Internal Server Errors

Symptoms: HTTP 500 status, “Internal Server Error” page.
Root Causes: Corrupt .htaccess, exhausted PHP memory, server misconfig.

Diagnosis

  • Check Apache/Nginx error logs (/var/log/apache2/error.log or via hosting panel).

  • Rename .htaccess to .htaccess.bak and reload site.

Fixes

  • Regenerate .htaccess:

    1. Go to Settings → Permalinks and click Save Changes.

  • Increase PHP Memory: (see above).

  • File Permissions: Ensure folders are 755, files 644.

  • Server Limits: Ask host to raise max_execution_time, max_input_vars, or post_max_size.

 

 

3. Plugin & Theme Conflicts

Symptoms: Layout breaks, fatal errors, missing functionality.
Root Causes: Two pieces of code overriding the same hook or template.

Diagnosis

  • Health Check & Troubleshooting plugin: activate, then in “Troubleshoot” mode use default theme and disable plugins for your user only.

  • Browser Console: look for JS errors that reference plugin files.

Fixes

  • Template Overrides:

    • Check your theme’s woocommerce/ folder for outdated templates (compare with plugin’s /templates).

  • Hook Priority: If two plugins use the same hook, adjust priority:

  • php

  • CopyInsert

  • add_action('woocommerce_before_checkout_form', 'my_function', 20);

  • Contact Developer: For paid themes or plugins, open a support ticket with conflict details.

 

 

4. Checkout Failures & Cart Not Updating

Symptoms: Cart remains empty; checkout form reloads with no feedback.
Root Causes: AJAX errors, session issues, mismatched SSL.

Diagnosis

  1. Open browser DevTools → Network tab → Add to Cart → watch for failed AJAX calls (500 or CORS).

  2. Check PHP error logs for session or cookie errors.

Fixes

  • Permalinks: Resave by Settings → Permalinks.

  • SSL Mismatch: Ensure your site URL is https:// in Settings → General.

  • Cookie Domain: In wp-config.php add:

  • php

  • CopyInsert

  • define('COOKIE_DOMAIN', $_SERVER['HTTP_HOST']);

  • Session Storage: Switch from file to DB sessions:

  • php

  • CopyInsert

  • add_filter('woocommerce_session_handler', function(){ return 'WC_Session_Handler_DB'; });

  • Disable Conflict Plugins: Temporarily disable caching or security plugins that minify AJAX.

 

 

5. Email Delivery Issues (Order Notifications)

Symptoms: Customers or admin not receiving order emails.
Root Causes: PHP mail() blocked, SPF/DKIM failure, spam filtering.

Diagnosis

  • Install WP Mail SMTP and enable debug logs.

  • Send a test email and review plugin log.

Fixes

  • SMTP Relay: Configure with Mailgun, SendGrid, or Postmark:

    • Install WP Mail SMTP.

    • Enter API key and set “From” address to your domain.

  • DNS Records: Add SPF, DKIM, and DMARC to your DNS zone:

  • CopyInsert

TXT @ "v=spf1 include:mailgun.org ~all"

  • TXT mg._domainkey "v=DKIM1; k=rsa; p=..."

  • WooCommerce Email Settings:

    • Go to WooCommerce → Settings → Emails.

    • Ensure “Enable this email notification” is checked for “New Order” and “Order Completed”.

 

 

6. Image Upload & Media Library Errors

Symptoms: Upload fails, “HTTP error,” missing files, 403 forbidden.
Root Causes: File permissions, mod_security, low PHP limits.

Diagnosis

  • Check /wp-content/uploads permissions (should be 755).

  • Test upload with smaller file (<500 KB) and then larger.

Fixes

  • Increase PHP Limits in php.ini or .user.ini:

  • CopyInsert

upload_max_filesize = 64M

post_max_size = 64M

  • memory_limit = 256M

  • Disable mod_security for uploads by asking host or adding in .htaccess:

  • CopyInsert

<IfModule mod_security.c>

  SecFilterEngine Off

  SecFilterScanPOST Off

  • </IfModule>

  • Regenerate Thumbnails: Install Regenerate Thumbnails plugin and run for all images.

 

 

7. Broken Links & 404s

Symptoms: Customers see 404 pages for products or categories.
Root Causes: Permalink changes, deleted pages, external link typos.

Diagnosis

  • Use Broken Link Checker plugin or a crawler like Screaming Frog.

Fixes

  • Restore Permalinks: Save Permalink settings.

  • 301 Redirects:

    • Install Redirection plugin and map old URLs to new ones.

  • Bulk Fix: In .htaccess, add if-then rules for known patterns:

  • apache

  • CopyInsert

  • RedirectMatch 301 ^/product/(.*)\.php$ [https://example.com/product/$1/](https://example.com/product/$1/)

 

 

8. Payment Gateway Declines & Timeouts

Symptoms: Transactions fail silently or show gateway errors.
Root Causes: API key misconfiguration, SSL issues, sandbox/live mismatch.

Diagnosis

  • Enable gateway logs in WooCommerce → Settings → Payments → [Gateway].

  • Review wp-content/uploads/wc-logs for error messages and HTTP status codes.

Fixes

  • API Credentials: Double‑check live vs. test keys.

  • SSL Validation: Ensure curl.cainfo is set in php.ini with your CA bundle path.

  • 3D Secure (SCA): Update gateway plugin to the latest version supporting SCA flows.

  • Webhook Retries: Verify webhook endpoint is reachable and not blocked by a security plugin.

 

 

9. Slow Page Loads & Timeouts

Symptoms: TTFB slow, pages time out, admin sluggish.
Root Causes: No caching, heavy queries, unoptimized images.

Diagnosis

  • Run GTmetrix, Pingdom, or Lighthouse.

  • Enable Query Monitor plugin to surface slow SQL queries.

Fixes

  • Object/Fragment Caching: Activate Redis or Memcached via hosting or Redis Object Cache plugin.

  • Page Caching: Use WP Rocket, W3 Total Cache, or host‑level caching.

  • Image Optimization: Serve WebP via Imagify or ShortPixel.

  • Disable Cart Fragments:

  • php

  • CopyInsert

add_action('wp_enqueue_scripts','disable_woocommerce_cart_fragments', 11);

function disable_woocommerce_cart_fragments(){

  wp_dequeue_script('wc-cart-fragments');

  • }

 

 

10. SSL Certificate & Mixed‑Content Warnings

Symptoms: “Secure” icon broken, browser warns about insecure assets.
Root Causes: Hard‑coded http:// URLs in theme, external scripts.

Diagnosis

  • Open DevTools → Console → look for “Mixed Content” errors.

Fixes

  • Force HTTPS in Settings → General: set both URLs to https://.

  • Search & Replace old URLs in database using Better Search Replace plugin.

  • Plugin: Install Really Simple SSL to handle redirects and rewrite content.

 

 

11. Database Connection Errors

Symptoms: “Error establishing a database connection”.
Root Causes: Wrong DB credentials, host unreachable, overloaded DB.

Diagnosis

  • Check DB constants in wp-config.php: DB_NAME, DB_USER, DB_PASSWORD, DB_HOST.

  • Ping MySQL host from SSH (mysql -h hostname -u user -p).

Fixes

  • Credentials: Copy/paste values from hosting panel.

  • Repair DB: In wp-config.php add:

  • php

  • CopyInsert

  • define('WP_ALLOW_REPAIR', true);
    Then visit [https://example.com/wp-admin/maint/repair.php.](https://example.com/wp-admin/maint/repair.php`.)

  • Optimize Tables: Via phpMyAdmin or:

  • bash

  • CopyInsert in Terminal

  • wp db optimize

 

 

12. Debugging Tools & Preventative Maintenance

Essential Plugins

  • Health Check & Troubleshooting: isolate issues without affecting live users.

  • Query Monitor: view hooks, SQL queries, REST calls, and PHP warnings.

  • WP Crontrol: manage scheduled events and cron jobs.

Best Practices

  • Staging Environment: Test all updates before production.

  • Regular Backups: Use UpdraftPlus or host‑provided snapshots.

  • Update Schedule: Weekly check for plugin, theme, and core updates.

  • Monitoring: Set up uptime alerts (UptimeRobot) and error notifications via Slack or email.

 

 

Frequently Asked Questions

Q1: My site went blank after a plugin update—how can I restore access?
Rename the plugin folder via FTP or your hosting file manager to deactivate. Then fix or replace the plugin.

Q2: How do I clear WooCommerce transients and sessions?
Use WP‑CLI:

CopyInsert

wp transient delete --all

wp option delete woocommerce_sessions

Q3: Orders are marked “Processing” but no email sent—why?
Check Mail SMTP logs, confirm “Order Processing” notification is enabled under WooCommerce → Settings → Emails.

 

 

Conclusion

Maintaining a healthy WooCommerce store means anticipating and resolving errors swiftly. Use core debugging tools (WP_DEBUG, Query Monitor), isolate conflicts in staging, enforce HTTPS, optimize performance with caching, and employ SMTP for reliable email. Regular updates, backups, and monitoring prevent issues from escalating. With these strategies, you’ll minimize downtime, improve conversion rates, and deliver a seamless shopping experience.