WooCommerce Fatal Error: A Practical Troubleshooting Guide

Symptoms

• There has been a critical error on this website on the shop, product pages, checkout or admin.
• A white screen or an HTTP 500 response.
• Checkout that keeps loading because its request fails with a 500.
• An email to the site administrator titled Your Site is Experiencing a Technical Issue.

Most common causes

Diagnosis

1. Get the full error

In order of convenience:

1. The email WordPress sends to the administrator when it catches a fatal error.
2. WooCommerce → Status → Logs, source fatal-errors.
3. The PHP error log in your hosting panel.
4. wp-content/debug.log, after enabling logging:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );      // or a path outside the web root
define( 'WP_DEBUG_DISPLAY', false ); // never show errors to customers
@ini_set( 'display_errors', '0' );

2. Read it in four parts

PHP Fatal error:  Uncaught TypeError: Unsupported operand types: string + float
  in /var/www/wp-content/plugins/custom-fees/custom-fees.php:142
Stack trace:
#0 /var/www/wp-includes/class-wp-hook.php(324): add_custom_fee(Object(WC_Cart))
#1 /var/www/wp-includes/plugin.php(205): WP_Hook->apply_filters(...)
#2 /var/www/wp-content/plugins/woocommerce/includes/class-wc-cart.php(...): do_action('woocommerce_cart_calculate_fees', ...)

• Type and message: a TypeError — wrong types, not a missing file.
• File and line: custom-fees.php:142 — a custom plugin, not WooCommerce.
• Stack trace: WooCommerce reached it while calculating cart fees.
• Timestamp (in the log line prefix): match it with the last update, deployment or PHP change.

3. Connect it to a change

Look at what changed just before the first occurrence: plugin and theme updates, a new snippet, a PHP version change, a WooCommerce update that changed what a hook passes. Most fatal errors are the first run of new code paths after a change.

Logs and technical checks

• fatal-errors log, PHP error log, debug.log.
• WooCommerce → Status → System status: PHP version, memory limit, WooCommerce and extension versions.
• The plugin's changelog for the version installed just before the error appeared.
• For memory errors: which request, how often, and what it was loading.

Solutions

• Roll back the component that introduced the error to its previous version, as a stopgap, while the real fix is prepared.
• Fix the code defensively: check return values, cast types, and handle missing orders or products.
• Update incompatible plugins for the current PHP and WooCommerce versions, or replace abandoned ones.
• Remove duplicates: the same snippet in a snippets plugin and in functions.php, or two plugins that bundle conflicting libraries.
• For time and memory limits, fix what is slow or heavy; raise limits only for legitimate heavy jobs, ideally in the background.

// Before: fatal when get_option() returns a string
$fee = $cart->get_subtotal() * get_option( 'handling_rate' );

// After: explicit types, and nothing to add when the rate is not set
$rate = (float) get_option( 'handling_rate', 0 );
if ( $rate > 0 ) {
    $cart->add_fee( __( 'Handling', 'my-store' ), $cart->get_subtotal() * $rate );
}

What not to do

• Do not enable error display on a live store; log errors instead.
• Do not edit a third-party plugin's files on production. The change is lost at the next update and nobody knows it exists.
• Do not reinstall WooCommerce or restore an old backup without knowing the cause — you may lose orders and keep the bug.
• Do not delete the log after reading it; you will need it to confirm the fix.

When to contact an expert

Contact an engineer when the error is inside custom code or a premium extension you cannot safely change, when it is intermittent, when it appeared after a PHP upgrade across many files, or when it blocks checkout or the admin right now.

Related problems

• WooCommerce / Errors WooCommerce Plugin Conflict: How to Find the Cause Start from the evidence — the error, the timing, the request — and isolate on staging by halves, not one plugin at a time on production. →
• WooCommerce / Checkout WooCommerce Checkout Not Working: How to Diagnose the Root Cause First determine whether the failure happens before the checkout request, during it, or after the gateway response. The Network panel and PHP logs usually reveal which layer fails. →
• WooCommerce / HPOS WooCommerce HPOS: Common Problems With Custom Code Direct wp_posts queries, get_post_meta() on orders and other code that silently breaks once orders live in their own tables. →

Frequently asked questions