Solución de problemas PrestaShop: Pantalla blanca, errores 500 y problemas comunes

La Mentalidad de Resolución de Problemas

Algo se rompió. El instinto es empezar a cambiar cosas. Resístase. Cambiar múltiples cosas a la vez hace imposible saber qué soluciónó el problema. El método que funciona: observar, aislar, corregir, verificar. Lea el error. Revise los logs. Cambie una sola cosa. Pruebe. Repita.

Antes de tocar nada, haga una copia de seguridad. Volcado de base de datos + archivo de ficheros. Si su corrección empeora las cosas, necesita una forma de volver atrás.

1. Activar el Modo Debug

El modo debug es su primera herramienta para cada problema. PrestaShop oculta los errores por defecto — bueno para los clientes, terrible para la resolución de problemas.

PrestaShop 1.6 y 1.7

Edite config/defines.inc.php:

define('_PS_MODE_DEV_', true);  // Change false to true

Esto activa la visualización de errores, desactiva la caché de Smarty y establece error_reporting en E_ALL. En PS 1.7.7+, también habilita la barra de herramientas de depuración de Symfony en la parte inferior de cada página.

PrestaShop 8.x y 9.x

El mismo enfoque con defines.inc.php funciona, pero PS 8+ también lee de .env:

# .env or .env.local
APP_ENV=dev
APP_DEBUG=1

Alternativa de Emergencia

Si el error ocurre antes de que PrestaShop cargue su configuración, fuerce la visualización de errores PHP al inicio de index.php:

ini_set('display_errors', 1);
error_reporting(E_ALL);

En PS 1.7.7+, el modo debug también habilita la barra del profiler de Symfony que muestra cada consulta a la base de datos, uso de memoria, aciertos/fallos de caché y plantillas renderizadas.

Nunca deje el modo debug activado en producción. Expone rutas de archivos, detalles de la base de datos y lógica interna a cualquier persona.

2. Pantalla Blanca de la Muerte (WSOD)

Una página completamente en blanco significa que PHP encontró un error fatal pero display_errors está desactivado. El error existe — simplemente está oculto.

Paso 1: Revise el Log de Errores

El error siempre se registra en algún lugar: var/logs/prod.log (PS 1.7), var/log/prod.log (PS 8+/9), log de errores de Apache o log de errores de PHP. En hosting compartido: ~/logs/error.log.

Paso 2: Active el Modo Debug

Si los logs no son accesibles, active _PS_MODE_DEV_ y recargue la página.

Paso 3: Verificación con PHP CLI

Si la página está completamente en blanco, pruebe con PHP: php -l config/defines.inc.php (verificación de sintaxis) o php -r "require 'config/config.inc.php';" (prueba de carga).

Causas Más Comunes

• Límite de memoria agotado: Aumente en php.ini: memory_limit = 512M (mínimo 256M para PS 1.7+, 512M para PS 8+).
• Versión de PHP incompatible: PS 1.6 falla con PHP 7.4+. PS 1.7.0-1.7.6 falla con PHP 8.0+. PS 9.x requiere PHP 8.1+.
• Error fatal en un módulo: Renombre la carpeta del módulo vía FTP: modules/problem_module a modules/problem_module_disabled.
• Caché corrupta: Elimine todo en var/cache/ (PS 1.7+) o cache/smarty/compile/ (PS 1.6).
• Override dañado: Renombre temporalmente el directorio override/ para probar.

3. Error 500 Internal Server Error

HTTP 500 significa que el servidor encontró una condición que no pudo manejar. A diferencia del WSOD, esto podría ni siquiera llegar a PHP.

Problemas con .htaccess

La causa más común. Pruebe renombrando temporalmente: mv .htaccess .htaccess.bak. Si el sitio carga (con URLs rotas), el .htaccess es el problema.

• mod_rewrite no habilitado: a2enmod rewrite && systemctl restart apache2
• AllowOverride None: Debe ser AllowOverride All en la configuración del virtual host.
• Directivas no soportadas: Algunos hostings compartidos bloquean Options o php_value. Comente secciones hasta encontrar la causante.
• Regenerar: Shop Parameters → Traffic & SEO → "Generate .htaccess file".

Permisos de Archivos

Directorios: 755, archivos: 644, directorios con escritura (var/cache, img, upload): 775. Nunca 777.

find /path/to/prestashop -type d -exec chmod 755 {} \;
find /path/to/prestashop -type f -exec chmod 644 {} \;

Límites de PHP

memory_limit = 512M
max_execution_time = 300
max_input_vars = 10000
post_max_size = 64M
upload_max_filesize = 64M

max_input_vars se suele pasar por alto — las páginas de producto de PS con combinaciones superan el valor predeterminado de 1000.

4. Conflictos de Módulos

Los módulos son la fuente más común de problemas. Dos módulos que intentan hacer lo mismo entrarán en conflicto.

El Método de Aislamiento

1. Desactive todos los módulos de terceros a través del Module Manager.
2. Confirme que el problema ha desaparecido.
3. Reactive los módulos uno por uno, probando después de cada uno.

Si el panel de administración está roto, desactive mediante la base de datos:

UPDATE ps_module SET active = 0 WHERE name = 'module_name';
-- Or rename the folder: mv modules/problem_module modules/problem_module.bak

Conflictos de Overrides

Dos módulos no pueden hacer override de la misma clase. Revise override/classes/ y override/controllers/. Si elimina un override manualmente, borre var/cache/*/class_index.php para forzar la regeneración.

Prioridad de Hooks

Cuando dos módulos usan el mismo hook, el orden de ejecución importa. Ajústelo en Design → Positions, o consulte ps_hook_module para ver el orden de ejecución por hook.

Al reportar un conflicto de módulos a un desarrollador, incluya: el error exacto del log, su versión de PS, versión de PHP, otros módulos activos y los pasos para reproducir el problema.

5. Problemas de Caché

PrestaShop tiene múltiples cachés independientes. Cuando "limpiar la caché" no funciona, probablemente limpió la incorrecta.

Las Capas de Caché

• Smarty: Archivos TPL compilados en var/cache/prod/smarty/.
• Symfony: Contenedores compilados, rutas y traducciones en var/cache/prod/.
• OPcache: Bytecode PHP en memoria compartida — invisible para el sistema de archivos.
• Caché de objetos: Caché de consultas a la base de datos (basada en archivos o Redis).
• Caché del navegador: CSS, JS e imágenes en el dispositivo del visitante.

Limpiar Todo

Panel de administración: Advanced Parameters → Performance → Clear cache. Cuando el admin está roto:

# Delete cache directories
rm -rf var/cache/prod/* var/cache/dev/*

# Or use Symfony console (PS 8+/9)
php bin/console cache:clear --env=prod

OPcache

Después de editar archivos PHP, OPcache puede seguir sirviendo la versión anterior. Reinicie mediante una solicitud web — cree un archivo temporal con opcache_reset();, visítelo en un navegador y elimínelo. El reinicio por CLI solo limpia la caché CLI, no la caché web.

Cuando la Caché se Queda "Atascada"

Haga coincidir la caché con el cambio: plantilla → Smarty, código PHP → OPcache, configuración → Symfony, CSS/JS → navegador (Ctrl+Shift+R). También verifique los permisos de var/cache/, elimine class_index.php para forzar la regeneración y purgue el CDN por separado.

Después de cada despliegue: limpie la caché de Symfony, la caché de Smarty, OPcache (vía web) y la caché del CDN. Si omite alguna, su despliegue parecerá que "no funcionó".

6. Problemas de Base de Datos

Los problemas de base de datos suelen aparecer después de actualizaciones fallidas, importaciones interrumpidas u operaciónes que excedieron el tiempo límite.

Tablas Corruptas

# Check all tables
mysqlcheck -u root -p prestashop_db --check

# Repair (MyISAM only)
REPAIR TABLE ps_product;

# For InnoDB (most modern installs), rebuild in place:
ALTER TABLE ps_product ENGINE=InnoDB;

Columnas Faltantes Tras una Actualización Fallida

Error: Unknown column 'new_column' in 'field list'. La actualización fue interrumpida, dejando tablas incompletas.

# Check what columns exist
SHOW CREATE TABLE ps_product\G

# Look for upgrade SQL in install-dev/upgrade/sql/ or install/upgrade/sql/
# Add the missing column manually:
ALTER TABLE ps_product ADD COLUMN `state` TINYINT(1) NOT NULL DEFAULT '1';

Comparar Estructuras

Instale una copia limpia de su versión de PS, exporte ambas estructuras con mysqldump --no-data y compárelas con diff para revelar tablas, columnas e índices faltantes.

Consultas Bloqueadas

Ejecute SHOW FULL PROCESSLIST para encontrar consultas bloqueadas, KILL <id> para terminarlas y SHOW ENGINE INNODB STATUS para verificar esperas de bloqueo.

Nunca ejecute ALTER TABLE en tablas grandes de producción durante horario laboral. Añadir una columna a una tabla con un millón de filas puede bloquearla durante minutos.

7. Problemas de Tema

Plantillas Faltantes

Error: unable to load template file 'module:modulename/...'. PrestaShop busca primero en el override del tema (themes/your_theme/modules/...) y luego en el valor predeterminado del módulo. Si un override del tema hace referencia a un archivo eliminado o renombrado, obtendrá este error. En Linux, los nombres de archivo distinguen entre mayúsculas y minúsculas.

Errores de Compilación de Smarty

Etiquetas desbalanceadas (cada {if} necesita {/if}), llaves de JavaScript (envuelva JS en {literal}{/literal}) y problemas de codificación (los archivos TPL deben ser UTF-8 sin BOM) son los culpables habituales.

Fallos en la Carga de Assets

Revise la consola del navegador (F12 → Network) en busca de errores 404. Causas comunes: rutas incorrectas en theme.yml, caché CCC corrupta, configuración incorrecta del CDN.

Problemas con Temas Hijo

Tema padre eliminado (el tema hijo falla con "Invalid theme"), overrides de plantillas obsoletos tras actualizaciones del tema padre, o un theme.yml incompleto en el tema hijo que provoca que los módulos desaparezcan de los hooks.

Al actualizar PrestaShop, revise el changelog en busca de cambios en plantillas. Los overrides del tema hijo sobre plantillas modificadas necesitan actualizarse.

8. Compatibilidad con Versiones de PHP

Matriz de Compatibilidad

* PS 1.7.8 tiene soporte parcial para PHP 8.0 — el núcleo funciona, pero muchos módulos no.

Errores Comunes de Actualización

• PHP 7.x → 8.0: TypeError: expects string, null given — PHP 8 es estricto con null en strlen(), strpos(), etc.
• PHP 8.0 → 8.1: Return type should be compatible — tipos más estrictos. FILTER_SANITIZE_STRING obsoleto.
• PHP 8.1 → 8.2: Propiedades dinámicas obsoletas.

Importante: las versiones de PHP en CLI y web pueden diferir en servidores con múltiples versiones de PHP. Siempre verifique con phpinfo() en un navegador, no solo con php -v. Antes de actualizar: pruebe en staging, ejecute php -l en los archivos del módulo y actualice los módulos primero.

9. El Correo Electrónico No Se Envía

• Pruebe desde el admin: Advanced Parameters → Email → "Send a test email."
• Verifique la configuración SMTP: Host, puerto (587/TLS o 465/SSL), usuario, contraseña.
• Revise la tabla ps_mail: Si los correos aparecen aquí, PS los envió — el problema es la entrega.
• PHP mail(): Si falla, cambie a SMTP — es más fiable en todas partes.
• Registros DNS: SPF, DKIM y DMARC son necesarios para la entrega moderna.

Guía completa: PrestaShop Email Deliverability.

10. El Rendimiento Cayó Repentinamente

Diagnóstico Rápido

Verifique el espacio en disco (df -h), la carga del servidor (uptime), MySQL (SHOW FULL PROCESSLIST) y el estado de OPcache. Los discos llenos hacen que todo falle silenciosamente.

Causas Comunes de Caídas Repentinas de Rendimiento

• Modo debug activado: Revise _PS_MODE_DEV_ primero. Esto resuelve más quejas de "tienda lenta" que cualquier otra cosa.
• Disco lleno: MySQL se cuelga, las cachés no pueden escribir, los logs no pueden rotar.
• Consulta deficiente en un módulo: Una consulta sin índice en una tabla grande puede añadir segundos a cada carga de página.
• Tareas cron acumulándose: Múltiples scripts de importación/indexación ejecutándose simultáneamente.
• Tablas infladas: ps_connections, ps_log, ps_cart crecen indefinidamente sin mantenimiento.

Guía completa: PrestaShop Performance Optimization.

11. Mensajes de Error Comunes Explicados

"Class 'SomeClass' not found"

Elimine var/cache/prod/class_index.php (se regenera automáticamente), ejecute composer dump-autoload (PS 1.7+) y verifique los nombres de archivo sensibles a mayúsculas/minúsculas en Linux. Si un módulo fue eliminado parcialmente, limpie las tablas ps_hook_module y ps_module.

"CSRF token error" / "Invalid token"

Sesión expirada (aumente session.gc_maxlifetime), múltiples pestañas del admin (actualice la página), proxy inverso eliminando cookies (excluya el admin del caché) o reloj del servidor incorrecto.

"Ajax error"

Abra DevTools (F12) → pestaña Network. Reproduzca el error. Encuentre la solicitud fallida (roja, estado 500). La pestaña Response muestra el error real de PHP.

"Allowed memory size exhausted"

Establezca memory_limit = 512M en php.ini o .htaccess. Si la tienda sigue necesitando más, hay una fuga de memoria en un módulo — use el profiler de Symfony para encontrar al culpable.

"Duplicate entry for key"

Una violación de restricción única. Común con importaciones de productos (referencias duplicadas), instalaciones de módulos en multitienda o al re-ejecutar actualizaciones fallidas.

"Deprecated: ..." (avalancha de avisos)

Es una advertencia, no un error. Para silenciarla: error_reporting = E_ALL & ~E_DEPRECATED. Mejor aún: actualice el módulo. Estas advertencias se convierten en errores fatales en la siguiente versión de PHP.

12. Recuperación de Emergencia

Restablecer la Contraseña de Administrador

Para PS 1.6/1.7 (hash MD5):

UPDATE ps_employee SET passwd = MD5(CONCAT(
    (SELECT value FROM ps_configuration WHERE name = '_COOKIE_KEY_'),
    'YourNewPassword!'
)) WHERE email = 'admin@yourdomain.com';

Para PS 8+/9 (bcrypt), suba un script PHP temporal que incluya config/config.inc.php, use PrestaShop\Core\Crypto\Hashing para generar el hash, actualice ps_employee y luego elimine el script inmediatamente.

Elimine el script de restablecimiento inmediatamente después de usarlo. Cualquiera que lo encuentre puede restablecer cualquier contraseña de administrador.

Desactivar un Módulo Dañado

-- Via database
UPDATE ps_module SET active = 0 WHERE name = 'broken_module';

-- Via filesystem (more reliable)
mv modules/broken_module modules/broken_module.disabled

Para desactivar todos los módulos de terceros a la vez, actualice ps_module estableciendo active = 0 para todas las entradas cuyo nombre NO esté en la lista de módulos nativos de PS (ps_banner, ps_categorytree, ps_facetedsearch, etc.).

Desactivar Overrides

// config/defines.inc.php
define('_PS_ALLOW_OVERRIDES_', false);

Restaurar desde una Copia de Seguridad

Ponga el sitio fuera de línea, restaure la base de datos (mysql -u root -p db < backup.sql), restaure los archivos, limpie todas las cachés (rm -rf var/cache/*), reinicie OPcache y luego verifique que la página principal, la página de producto, el carrito, el checkout y el admin funcionen correctamente.

Modo Mantenimiento Sin Acceso al Admin

UPDATE ps_configuration SET value = '0' WHERE name = 'PS_SHOP_ENABLE';
UPDATE ps_configuration SET value = 'your.ip' WHERE name = 'PS_MAINTENANCE_IP';

13. Lista de Verificación de Diagnóstico

Imprima esto y trabaje de arriba a abajo cuando algo salga mal.

Fase 1: Recopilar Información

• ¿Qué cambió? ¿Instalación/actualización de módulo, actualización de PS, actualización de PHP, cambio de servidor, edición de tema?
• ¿Cuándo empezó exactamente? Cruce referencias con los logs de despliegue y las tareas cron.
• ¿A quién afecta? ¿A todos los usuarios, navegadores específicos, solo al admin, solo al front office?
• ¿Cuál es el error exacto? Active el modo debug. Revise la consola del navegador. Revise todos los logs.

Fase 2: Aislar

• Servidor: espacio en disco (df -h), memoria (free -m), CPU (top), MySQL (SHOW PROCESSLIST)
• PHP: versión (php -v), verificación de sintaxis (php -l), configuración (phpinfo())
• Caché: limpie todas las capas — Smarty, Symfony, OPcache, navegador. Pruebe en modo incógnito.
• Módulos: desactive los modificados recientemente. Si no está claro, desactive todos los de terceros y reactive uno por uno.
• Tema: cambie al predeterminado temporalmente.
• Base de datos: mysqlcheck, log de errores de MySQL, compare estructuras de tablas si fue después de una actualización.
• Permisos: ls -la en var/cache, var/logs, img, upload.

Fase 3: Corregir y Verificar

• Haga UN solo cambio a la vez. Pruebe. Si no lo soluciónó, revierta e intente el siguiente.
• Limpie todas las cachés después de cada corrección.
• Pruebe exhaustivamente: página principal, categoría, producto, carrito, checkout, admin.
• Pruebe en modo incógnito o en un navegador diferente.
• Desactive el modo debug. Elimine los scripts temporales.

Fase 4: Prevenir la Recurrencia

• Documente qué sucedió y qué lo soluciónó.
• Configure monitoreo: uptime, logs de errores, espacio en disco.
• Verifique que las copias de seguridad funcionen. Pruebe una restauración.

Referencia Rápida

Ubicación de Logs

• PS 1.6: log/ — PS 1.7: var/logs/ — PS 8+/9: var/log/
• Apache: /var/log/apache2/error.log — Nginx: /var/log/nginx/error.log
• MySQL: /var/log/mysql/error.log — PHP: según error_log en php.ini

Archivos Clave

• config/defines.inc.php — modo debug, activación de overrides
• app/config/parameters.php — credenciales de BD, secreto (PS 1.7+)
• .env / .env.local — entorno y debug (PS 8+)
• .htaccess — reescritura de URLs, configuración PHP, seguridad

Comandos CLI Esenciales (PS 1.7+)

php bin/console cache:clear --env=prod
php bin/console prestashop:module list
php bin/console prestashop:module enable module_name
php bin/console prestashop:module disable module_name
composer dump-autoload -o

Cada sesión de resolución de problemas comienza de la misma forma: revise el error, revise los logs, aísle la causa. Los desarrolladores más experimentados no memorizan cada error — saben dónde buscar. Esta guía le proporciona esas ubicaciones.