Recupera WordPress tras actualizaciones fallidas de plugins

¿Pantalla blanca, error 500 o web en modo mantenimiento justo después de actualizar plugins? Quien gestione un WordPress en producción necesita recuperar la web de inmediato, minimizar el downtime y preservar datos críticos mientras diagnostica la causa y evita que vuelva a ocurrir.

Resumen del proceso

Este resumen ofrece la hoja de ruta que recupera la web con mínima pérdida de servicio. Cada paso se puede ejecutar con comandos listos para copiar y pegar. Tiempo estimado: 10–30 minutos para triage y recuperación parcial; 20–90 minutos para rollback completo según tamaño del backup.

Paso rápido: desbloqueo y acceso

1. Quitar o renombrar .maintenance y confirmar ausencia de procesos PHP colgados. 2. Verificar espacio en disco y límites PHP. 3. Desactivar plugin problemático con wp‑cli o renombrando la carpeta.

Paso medio: diagnóstico reproducible

1. Reproducir actualización con wp‑cli --debug y guardar salida. 2. Revisar PHP/nginx/apache logs y debug.log de WordPress. 3. Si procede, restaurar backup y reinstalar plugin manualmente.

Paso 1: triage inmediato y recuperación rápida

El triage inmediato busca devolver la web a servicio visible en menos de 10 minutos. Primero se quita el bloqueo de mantenimiento, luego se comprueba espacio y procesos PHP, y por último se desactiva el plugin problemático. Si no hay SSH, pida al hosting que ejecute los pasos y comparta logs.

Quitar .maintenance y confirmar procesos

Mueva el archivo en lugar de borrarlo para conservar la información: mv .maintenance .maintenance.bak. Luego busque procesos PHP colgados con ps. Ejecución típica: ssh usuario@host "cd /ruta/web && [ -f .maintenance ] && mv .maintenance .maintenance.bak || true". Esto suele tardar 1–3 minutos.

Comprobar espacio y límites PHP

Compruebe uso de disco: df -h /ruta | awk 'NR==2{print $5}' y libere espacio si uso >= 90%. Revise php.ini o valores del hosting para post_max_size, upload_max_filesize y max_execution_time. Muchos fallos vienen por cuotas y límites bajos.

Paso 2: diagnóstico con logs y wp‑cli

Combine la salida de wp‑cli --debug con los logs del servidor para identificar descarga, permisos o incompatibilidades. Reproducir la actualización en un entorno controlado permite aislar el error sin afectar a usuarios. En la mayoría de casos, wp‑cli --debug muestra la causa directa en menos de 5 minutos.

Logs representativos y cómo

Ejemplo claro de error de incompatibilidad: [20-Jun-2024 10:12:34 UTC] PHP Fatal error: Uncaught Error: Call to undefined function nombre() in /ruta/wp-content/plugins/plugin/file.php:123. Este tipo de línea indica que el plugin usa funciones no soportadas por la versión PHP del servidor.

Reproducir actualización con wp‑cli

Comando reproducible: sudo -u www-data wp plugin update nombre-plugin --path=/ruta/web --debug 2>&1 | tee /tmp/wp-update-debug.log. Buscar en el log palabras clave: "curl", "Permission denied", "Fatal error". Si aparece "curl: (28)" es timeout de descarga.

En el diagnóstico conviene guardar ejemplos reproducibles de logs y saber leerlos:

• por ejemplo, una línea como [20-Jun-2024 10:12:34 UTC] PHP Fatal error: Call to undefined function nombre() in /ruta/wp-content/plugins/plugin/file.php:123 apunta a incompatibilidad con la versión de PHP o a dependencias faltantes
• una línea tipo curl: (28) Operation timed out o HTTP request failed con código 28 indica timeout de descarga o problemas de DNS
• un mensaje permission denied al intentar abrir /ruta/wp-content/upgrade/tmp-zip.zip muestra fallo de permisos en wp-content/upgrade
• y errores ZIP open error: cannot open file /tmp/plugin.zip suelen indicar descarga corrupta o espacio insuficiente. Para extraer estas entradas use comandos reproducibles como tail -n 200 /var/log/nginx/error.log | sed -n '1,200p', grep -iE 'curl|timeout|Permission denied|Fatal error' /tmp/wp-update-debug.log y cat wp-content/debug.log | tail -n 200. Interpretar cada patrón permite decidir: timeout → aumentar max_execution_time o usar wget con retries
• Permission denied → corregir chown/chmod en wp-content/upgrade
• ZIP errors → reintentar descarga con wget y verificar df -h para espacio en disco

Estos ejemplos y comandos transforman el log en acciones reproducibles durante el triage.

Paso 3: rollback y restauración desde backup

Si la actualización rompe funcionalidades críticas, restaure desde el backup completo (ficheros y base de datos). Un rollback ordenado restaura servicio y deja los datos intactos si se sigue el orden: ficheros, base de datos, permisos y comprobaciones. Restauración completa suele tardar 20–90 minutos según el tamaño del sitio.

Restaurar ficheros

Ejemplo con tar en servidor: ssh usuario@host "cd /ruta && tar -xzvf /backups/backup-2026-06-19.tar.gz -C /ruta --strip-components=1". Para backups grandes esto puede tardar 10–45 minutos. Si usa SFTP, subir y descomprimir con unzip es alternativa viable.

Restaurar base de datos y comprobaciones

Importe SQL: mysql -u db_user -p db_name < /backups/db-2026-06-19.sql y luego confirme con: mysql -u db_user -p db_name -e "SELECT COUNT(*) FROM wp_options WHERE option_name='siteurl'". Esto valida que la base de datos está consistente.

Antes de cualquier rollback pleno, haga un volcado inmediato de la base de datos y tablas críticas para no perder usuarios o pedidos recientes: use mysqldump --single-transaction --quick --lock-tables=false -u db_user -p db_name > /tmp/db-before-rollback.sql para una copia completa sin bloquear mucho tiempo, y exporte además tablas críticas por separado, por ejemplo mysqldump -u db_user -p db_name wp_users wp_usermeta wp_posts wp_postmeta wp_comments > /tmp/critical-tables.sql. Si restaura ficheros primero (tar/unzip), importe luego la base de datos con mysql -u db_user -p db_name < /backups/db.sql. Si necesita preservar registros de usuarios creados entre el fallo y la restauración, restaure la copia completa y a continuación importe solo las tablas críticas desde /tmp/critical-tables.sql con mysql -u db_user -p db_name < /tmp/critical-tables.sql; verifique con mysql -u db_user -p db_name -e "SELECT COUNT(*) FROM wp_users;" que los recuentos coinciden.

Este flujo asegura que el sitio vuelva funcional y que no se pierdan usuarios, formularios o pedidos generados desde el incidente.

Paso 4: reparos de permisos y mu-plugins / repos privados

Ajuste propietario y permisos antes de reinstalar para evitar que el updater cree ficheros con ownership erróneo. En entornos con repositorios privados o mu-plugins, asegúrese de tokens válidos y del usuario que ejecuta wp‑cli. Con permisos correctos, las reinstalaciones automáticas fallan menos.

Permisos y propietario seguros

Comandos seguros:

• sudo chown -R www-data:www-data /ruta/web
• find /ruta/web -type d -exec chmod 755 {} /;
• find /ruta/web -type f -exec chmod 644 {} /;

Sustituya www-data por el usuario que el hosting indique si procede. Esto suele tardar 2–10 minutos.

Repositorios privados y mu-plugins

Para GitHub/Composer, compruebe auth.json o .netrc con token válido. Ejemplo composer: composer config -g github-oauth.github.com token_value. Para mu-plugins, valide rutas y que el plugin no cargue antes de WP-DB: los mu-plugins se cargan siempre y pueden romper la actualización si tienen dependencias rotas.

En multisite hay matices operativos que merecen comandos concretos:

• para desactivar un plugin a nivel de red use sudo -u www-data wp plugin deactivate nombre-plugin --network --path=/ruta/web
• para desactivarlo solo en un site concreto use sudo -u www-data wp plugin deactivate nombre-plugin --url=sub.example.com --path=/ruta/web. Para actualizar network-activated plugins: sudo -u www-data wp plugin update nombre-plugin --network --path=/ruta/web --debug. Los uploads en multisite residen en wp-content/uploads/sites/<blog_id>/, tenga esto en cuenta al restaurar ficheros
• no sobrescriba accidentalmente sites/ de otros blogs. Los mu-plugins están en wp-content/mu-plugins/ y se cargan siempre, así que al diagnosticar errores de actualización renombre temporalmente la entrada problemática (mv wp-content/mu-plugins/plugin.php wp-content/mu-plugins/plugin.php.disabled) antes de reinstalar. Para repositorios privados en multisite, use claves SSH o auth.json de Composer por sitio/usuario: composer config -g github-oauth.github.com token_value o genere una clave con ssh-keygen -t ed25519 y añádala como deploy key en el repo
• asegúrese de que el usuario que ejecuta wp-cli tenga acceso a esas credenciales

Estas instrucciones reducen riesgos en entornos multisite y permiten actualizaciones y rollbacks controlados.

Comparativa de métodos de actualización

Esta tabla compara métodos según tiempo de efecto, posibilidad de rollback sin backup, necesidad de SSH y aptitud para multisite. Use la fila que mejor se adapte al entorno del sitio.

Cuándo usar WP‑CLI

Use WP‑CLI cuando tenga SSH y necesite trazabilidad y reproducibilidad. WP‑CLI permite --debug, registrar la salida y automatizar rollback en scripts.

Cuándo usar FTP o panel

Use FTP/SFTP para repos privados o cuando no haya SSH. Use el panel si el sitio no es crítico y no dispone de acceso técnico. FTP es más lento y tiene mayor riesgo de errores humanos.

Errores que arruinan el resultado y excepciones

Esta sección recoge fallos habituales y cuándo no aplicar los pasos anteriores. Identificar estas trampas evita perder datos o empeorar la recuperación. La mayoría de problemas provienen de errores humanos o de asumir que el hosting aplica las mismas rutas de usuario.

Errores comunes que complican la recuperación

El error más frecuente en este punto es renombrar carpetas de plugins sin exportar opciones, lo que provoca pérdida de configuración y complicaciones en la restauración. Otro error común es borrar entradas de la base de datos sin exportarlas.

Excepciones reales y cuándo no aplicarlas

Si quiere ayuda inmediata y dispone de acceso SSH, logs y copia de seguridad reciente, solicite soporte técnico indicando: timestamp del incidente, salida de wp‑cli --debug y /var/log/nginx/error.log. Esto acelera la intervención.

Preguntas frecuentes

¿Cuál es el primer paso si mi sitio muestra errores tras una actualización?

Quitar o renombrar .maintenance y comprobar espacio en disco. Si el problema persiste, desactive el plugin con wp‑cli o renombre su carpeta. Esta primera comprobación suele devolver la web en menos de 10 minutos.

¿Qué indica el error "Actualización fallida: -1"?

Significa habitualmente un timeout o fallo HTTP en la descarga. Reproduzca la actualización con wp‑cli --debug y compruebe curl o wget para confirmar un código 28 o problemas de DNS/HTTPS.

¿Puedo restaurar sin perder datos de los usuarios?

Sí si la restauración incluye la base de datos actualizada o si antes del rollback se exportaron tablas de usuarios. Restaurar solo ficheros puede dejar la DB con cambios recientes; por eso siempre exporte la DB antes de cualquier cambio destructivo.

¿Cómo saco logs útiles para soporte técnico?

Genere wp‑cli --debug y guarde /var/log/nginx/error.log y wp-content/debug.log. Comprima los archivos y adjúntelos al soporte. Los logs permiten encontrar permisos, timeouts y errores fatales.

¿Quién debe ejecutar los comandos si el servidor está gestionado por el hosting?

Ejecute wp‑cli con el mismo usuario del proceso web: sudo -u www-data wp ...; sustituya www-data por el usuario que el hosting use. Ejecutar como root puede crear ficheros con propietario incorrecto.

¿Qué método es más seguro en multisite?

WP‑CLI ejecutado con el usuario del proceso web suele ser la opción más segura y rápida para multisite, porque respeta permisos y permite actualizar network-activated plugins de forma trazable.

Checklist y comandos listos

A continuación está el checklist y los comandos listos para copiar. Siga el orden y verifique cada resultado antes de pasar al siguiente paso. Mantenga una copia del estado actual antes de cualquier acción.

Checklist mínimo

• Exportar base de datos actual: mysqldump -u db_user -p db_name > /tmp/db-before-rollback.sql
• Mover .maintenance: mv /ruta/web/.maintenance /ruta/web/.maintenance.bak
• Comprobar uso disco: df -h /ruta | awk 'NR==2{print $5}'
• Revisar procesos PHP: ps aux | egrep 'php-fpm|php|wp-cron'
• Reproducir actualización con wp‑cli: sudo -u www-data wp plugin update nombre-plugin --path=/ruta/web --debug 2>&1 | tee /tmp/wp-update-debug.log
• Si restaura ficheros: tar -xzvf /backups/backup.tar.gz -C /ruta --strip-components=1
• Restaurar DB: mysql -u db_user -p db_name < /backups/db.sql
• Ajustar permisos: sudo chown -R www-data:www-data /ruta/web && find /ruta/web -type d -exec chmod 755 {} /; && find /ruta/web -type f -exec chmod 644 {} /;

Scripts útiles

bash cd /ruta/web || exit [ -f .maintenance ] && mv .maintenance .maintenance.bak || echo 'no .maintenance'

sudo -u www-data wp plugin update nombre-plugin --path=/ruta/web --debug 2>&1 | tee /tmp/wp-update-debug.log

wget https://downloads.wordpress.org/plugin/nombre-plugin.latest-stable.zip -O /tmp/plugin.zip unzip -o /tmp/plugin.zip -d /ruta/web/wp-content/plugins/ sudo chown -R www-data:www-data /ruta/web/wp-content/plugins/nombre-plugin

mysqldump -u db_user -p db_name > /tmp/db-before-delete.sql && mysql -u db_user -p db_name -e "DELETE FROM wp_options WHERE option_name='core_updater.lock';" && echo 'Se ha exportado la BD antes de eliminar el lock. No borre .maintenance: elimine o mueva el archivo /ruta/web/.maintenance si existe.'

Referencias: documentación de actualizaciones en WordPress.org y guías de proveedores como WP Engine y SiteGround sobre backups y permisos.

• Asegura backups PCI-DSS y pasa auditorías
• Backups de WordPress: recuperación segura y verificada

Josu Barrios

Somos especialistas en mantenimiento WordPress para empresas, profesionales y tiendas online. Contamos con experiencia en seguridad web, optimización de rendimiento, actualizaciones, copias de seguridad y resolución de incidencias técnicas, ayudando a que cada sitio funcione de forma rápida, estable y protegida. Nuestro enfoque combina soporte técnico profesional, buenas prácticas de seguridad y seguimiento continuo para ofrecer un servicio fiable, transparente y orientado a resultados reales.