Error fatal en WooCommerce: guía práctica para resolverlo

Síntomas

• Ha habido un error crítico en esta web en la tienda, las fichas de producto, el checkout o la administración.
• Una pantalla en blanco o una respuesta HTTP 500.
• Un checkout que no deja de cargar porque su petición falla con un 500.
• Un email al administrador con el asunto Tu sitio está teniendo un problema técnico.

Causas más comunes

Diagnóstico

1. Consigue el error completo

Por orden de comodidad:

1. El email que WordPress envía al administrador cuando captura un error fatal.
2. WooCommerce → Estado → Registros, origen fatal-errors.
3. El log de errores PHP del panel del hosting.
4. wp-content/debug.log, tras activar el registro:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );      // o una ruta fuera de la raíz web
define( 'WP_DEBUG_DISPLAY', false ); // nunca muestres errores a los clientes
@ini_set( 'display_errors', '0' );

2. Léelo en cuatro partes

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', ...)

• Tipo y mensaje: un TypeError, es decir, tipos incorrectos, no un archivo que falta.
• Archivo y línea: custom-fees.php:142, un plugin a medida, no WooCommerce.
• Traza: WooCommerce llegó ahí mientras calculaba los cargos del carrito.
• Hora (en el prefijo de la línea del registro): relaciónala con la última actualización, despliegue o cambio de PHP.

3. Relaciónalo con un cambio

Mira qué cambió justo antes de la primera aparición: actualizaciones de plugins y del tema, un snippet nuevo, un cambio de versión de PHP, una actualización de WooCommerce que cambió lo que pasa un hook. La mayoría de los errores fatales son la primera ejecución de un camino de código nuevo tras un cambio.

Registros y comprobaciones técnicas

• Registro fatal-errors, log de errores PHP, debug.log.
• WooCommerce → Estado → Estado del sistema: versión de PHP, límite de memoria, versiones de WooCommerce y de las extensiones.
• El changelog del plugin para la versión instalada justo antes de que apareciera el error.
• Para errores de memoria: qué petición, con qué frecuencia y qué estaba cargando.

Soluciones

• Revierte el componente que introdujo el error a su versión anterior, como medida provisional, mientras se prepara el arreglo real.
• Arregla el código de forma defensiva: comprueba los valores devueltos, convierte los tipos y gestiona pedidos o productos inexistentes.
• Actualiza los plugins incompatibles con las versiones actuales de PHP y WooCommerce, o sustituye los abandonados.
• Elimina duplicados: el mismo snippet en un plugin de snippets y en functions.php, o dos plugins que incluyen librerías en conflicto.
• Para los límites de tiempo y memoria, arregla lo que es lento o pesado; sube los límites solo para tareas pesadas legítimas, idealmente en segundo plano.

// Antes: error fatal cuando get_option() devuelve un texto
$fee = $cart->get_subtotal() * get_option( 'handling_rate' );

// Después: tipos explícitos, y nada que añadir si la tasa no está configurada
$rate = (float) get_option( 'handling_rate', 0 );
if ( $rate > 0 ) {
    $cart->add_fee( __( 'Gastos de gestión', 'my-store' ), $cart->get_subtotal() * $rate );
}

Qué no hacer

• No actives la visualización de errores en una tienda en producción; regístralos.
• No edites los archivos de un plugin de terceros en producción. El cambio se pierde con la siguiente actualización y nadie sabe que existe.
• No reinstales WooCommerce ni restaures una copia antigua sin conocer la causa: puedes perder pedidos y quedarte con el fallo.
• No borres el registro después de leerlo; lo necesitarás para confirmar el arreglo.

Cuándo recurrir a un experto

Recurre a un ingeniero cuando el error está dentro de código a medida o de una extensión premium que no puedes cambiar con seguridad, cuando es intermitente, cuando apareció en muchos archivos tras actualizar PHP, o cuando bloquea el checkout o la administración ahora mismo.

Problemas relacionados

• WooCommerce / Errores Conflicto de plugins en WooCommerce: cómo encontrar la causa Parte de las evidencias (el error, el momento, la petición) y aísla en staging por mitades, no plugin a plugin en producción. →
• WooCommerce / Checkout El checkout de WooCommerce no funciona: cómo diagnosticar la causa raíz Determina primero si el fallo ocurre antes de la petición del checkout, durante ella o después de la respuesta de la pasarela. El panel de red y los registros PHP suelen revelar qué capa falla. →
• WooCommerce / HPOS HPOS en WooCommerce: problemas habituales con código personalizado Consultas directas a wp_posts, get_post_meta() sobre pedidos y otro código que falla en silencio cuando los pedidos pasan a sus propias tablas. →

Preguntas frecuentes