WordPress atascado en modo mantenimiento: elimínalo de forma segura y evita que vuelva a suceder

El mensaje “Briefly unavailable for scheduled maintenance” de WordPress es el equivalente en software a un portero que sale a fumar y cierra el edificio con llave detrás de sí.

A veces desaparece en segundos. Otras veces permanece durante horas porque una actualización murió a mitad de camino, PHP agotó tiempo, el disco se llenó o un modelo de permisos se “endureció” hasta dejar de funcionar. La buena noticia: la solución suele ser sencilla. La mala noticia: puedes empeorar la situación si lo tratas como una simple reparación.

Qué es realmente el modo mantenimiento (y qué no es)

El modo mantenimiento de WordPress no es un “modo” en un sentido sofisticado. Es un archivo. Específicamente, un archivo llamado .maintenance en el directorio raíz de tu WordPress. Durante actualizaciones de core/plugins/temas, WordPress coloca este archivo como una bandera y lo comprueba en cada petición. Si existe y su marca temporal es lo bastante reciente, WordPress muestra el mensaje de mantenimiento y se detiene.

Esa simplicidad es a la vez una ventaja y una trampa. Si una actualización finaliza normalmente, WordPress borra el archivo. Si la actualización se interrumpe—timeout, error fatal, worker PHP terminado, problema de permisos, quedarse sin disco, lo que sea—el archivo puede quedarse. Y tu sitio sigue “brevemente no disponible” el tiempo que tu negocio tolere la vergüenza.

El modo mantenimiento también se confunde con:

• Un CDN o proxy inverso que cachea la página de mantenimiento mucho después de que el archivo haya desaparecido.
• Una función de “modo mantenimiento” de un plugin que no tiene relación con el mecanismo core de .maintenance.
• Una actualización rota donde el sitio está realmente caído (errores fatales), y la página de mantenimiento solo fue el primer síntoma que notaste.

Operativamente, trata el modo mantenimiento como un archivo de bloqueo. Tu trabajo es responder dos preguntas antes de eliminarlo: (1) ¿sigue ejecutándose una actualización? y (2) ¿falló de forma que dejó el sistema inconsistente?

Guía rápida de diagnóstico (primero/segundo/tercero)

Si tienes cinco minutos y alguien está mirando tu pantalla, haz esto en orden. El objetivo es encontrar el cuello de botella rápido: actualización atascada, estado del sistema de ficheros roto o una caché de borde que te está mintiendo.

Primero: confirma lo que realmente ven los usuarios

1. Obtén cabeceras y contenido desde el origen (evita el CDN si puedes). Si ves el HTML de mantenimiento desde el origen, es real. Si solo lo muestra el CDN, está cacheado.
2. Busca .maintenance y su marca temporal. Si es antiguo, casi con seguridad está obsoleto.

Segundo: decide si una actualización aún se está ejecutando

1. Busca procesos PHP activos que consuman CPU/tiempo, y revisa los logs del servidor web en busca de peticiones de larga duración alrededor de update.php o admin-ajax.php.
2. Comprueba el estado de actualizaciones de WordPress con WP-CLI si está disponible.

Tercero: valida que el sitio no se vaya a romper cuando quites el archivo

1. Revisa el espacio libre en disco (las actualizaciones escriben muchos archivos pequeños y descomprimen archivos).
2. Revisa la propiedad/permisos de archivos para wp-content y los directorios core.
3. Busca artefactos de actualizaciones incompletas como wp-content/upgrade y directorios de plugins parcialmente extraídos.

Eso es todo. No empieces a eliminar carpetas de plugins al azar como si jugaras a golpear topos con el sistema de archivos.

Eliminar el modo mantenimiento de forma segura: el camino disciplinado

Sí, el consejo común es “borrar .maintenance.” A veces eso es suficiente. Pero en producción, “suficiente” es como conseguir una indisponibilidad más larga que el banner de mantenimiento.

Este es el flujo disciplinado que uso en sistemas reales:

1. Identifica la raíz de WordPress (no adivines; en hosting compartido es fácil equivocarse).
2. Confirma que el archivo existe y léelo. Contiene una marca temporal y a veces indica qué actualización lo disparó.
3. Comprueba si las actualizaciones siguen en curso (lista de procesos, logs, estado WP-CLI).
4. Haz una snapshot o copia de seguridad antes de cambiar si estás en un sistema con rollback (snapshot de VM, snapshot ZFS, backup del hosting). Si no tienes rollback, sé extra cauteloso.
5. Quita el bloqueo borrando .maintenance solo después de estar seguro de que no hay actualizaciones activas.
6. Valida el sitio (página principal, wp-admin, una página sin sesión iniciada, una acción con sesión iniciada).
7. Finaliza o rehace la actualización de forma limpia para volver a un estado consistente.

Una cita que vale la pena tener en la cabeza cuando te tiente “simplemente borrar el archivo y largarte”:

“La esperanza no es una estrategia.” — atribuido a muchos líderes de operaciones; usado comúnmente en ingeniería de fiabilidad

Ahora vamos al trabajo práctico.

Tareas prácticas: comandos, salidas, decisiones (12+)

Supuestos para los ejemplos:

• Host Linux con Nginx o Apache
• WordPress ubicado en /var/www/html
• WP-CLI puede o no estar instalado

Si tus rutas difieren, ajústalas. No “hagas que funcione” copiando comandos a ciegas.

Task 1: Verifica que estás apuntando al origen (no a una caché)

cr0x@server:~$ curl -sS -D- -o /dev/null https://example.com/ | sed -n '1,20p'
HTTP/2 503
date: Sat, 27 Dec 2025 10:18:02 GMT
content-type: text/html; charset=UTF-8
cache-control: no-cache, must-revalidate, max-age=0
server: nginx

Qué significa: Un 503 sugiere que el handler de mantenimiento (o algo aguas arriba) está sirviendo un error. El cache-control insinúa que puede ser dinámico, pero no lo asumas.

Decisión: Si ves cabeceras de un CDN (por ejemplo, via o cabeceras específicas del CDN), prueba el origen directamente (host header a la IP de origen, o dirección del LB interno). Si el origen está bien pero el CDN no, estás lidiando con cacheo, no con WordPress.

Task 2: Confirma el contenido de la página de mantenimiento

cr0x@server:~$ curl -sS https://example.com/ | sed -n '1,5p'
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Briefly unavailable for scheduled maintenance. Check back in a minute.</title>

Qué significa: Ese es el mensaje canónico de mantenimiento de WordPress.

Decisión: Procede a las comprobaciones del sistema de ficheros. Si el contenido difiere, puede que estés mirando una página de mantenimiento de un plugin, un bloqueo de WAF o una página de error personalizada.

Task 3: Encuentra la raíz de WordPress (no adivines)

cr0x@server:~$ sudo find /var/www -maxdepth 4 -name wp-config.php -print
/var/www/html/wp-config.php

Qué significa: El directorio que contiene wp-config.php suele ser la raíz de tu WordPress.

Decisión: Usa ese directorio para todas las operaciones posteriores. Si hay múltiples resultados, relaciónalos con los vhosts antes de cambiar nada.

Task 4: Comprueba si .maintenance existe y su antigüedad

cr0x@server:~$ cd /var/www/html && sudo ls -la .maintenance
-rw-r--r-- 1 www-data www-data 114 Dec 27 09:01 .maintenance

Qué significa: El archivo existe, propiedad del usuario web. La marca temporal sugiere que lleva más que un “momento”.

Decisión: Si es más antiguo que unos minutos y no hay una actualización en curso, probablemente esté obsoleto y sea seguro eliminarlo tras la validación.

Task 5: Lee el archivo .maintenance para contexto

cr0x@server:~$ sudo cat /var/www/html/.maintenance
<?php $upgrading = 1766826061; ?>

Qué significa: Registra una marca temporal Unix en $upgrading. WordPress la usa para decidir si aplicar el modo mantenimiento.

Decisión: Conviértela a hora humana. Si es antigua, no estarás interrumpiendo una actualización activa al eliminarla.

Task 6: Convierte la marca temporal de upgrading

cr0x@server:~$ date -d @1766826061
Sat Dec 27 09:01:01 UTC 2025

Qué significa: El mantenimiento empezó a las 09:01 UTC.

Decisión: Si ahora estás muy por detrás de esa hora, asume que la actualización falló o fue terminada.

Task 7: Busca procesos de actualización activos (PHP-FPM / PHP)

cr0x@server:~$ ps aux | egrep 'php-fpm|php.*wp-admin|php.*update' | head
www-data  21314  0.0  0.6 373400 53324 ?        S    10:12   0:00 php-fpm: pool www
www-data  21315  0.0  0.6 373400 53288 ?        S    10:12   0:00 php-fpm: pool www

Qué significa: Ves workers PHP-FPM, pero nada que grite “ejecutando una actualización”. Eso es tráfico normal.

Decisión: Si ves un proceso PHP de larga ejecución ligado a un endpoint de actualización, espera o investiga los logs antes de borrar el bloqueo.

Task 8: Revisa los logs de error del servidor web por fallos de actualización

cr0x@server:~$ sudo tail -n 30 /var/log/nginx/error.log
2025/12/27 09:01:32 [error] 21001#21001: *188 FastCGI sent in stderr: "PHP message: PHP Fatal error:  Uncaught Error: Call to undefined function ..." while reading response header from upstream, client: 203.0.113.10, server: example.com, request: "GET /wp-admin/update.php?action=update-plugin&plugin=foo/bar.php HTTP/2.0"

Qué significa: Una petición de actualización produjo un error fatal a mitad de ejecución. Esa es una forma clásica de dejar .maintenance atrás.

Decisión: Espera encontrar un plugin/tema/core parcialmente actualizado. Planea reparar reinstalando el componente afectado de forma limpia después de restaurar el acceso.

Task 9: Comprueba el espacio en disco (las actualizaciones fallan silenciosamente cuando el almacenamiento está justo)

cr0x@server:~$ df -h /var/www/html
Filesystem      Size  Used Avail Use% Mounted on
/dev/sda1        40G   39G  420M  99% /

Qué significa: 99% lleno. Eso no es “un poco justo”, es “tu próxima escritura fallará”. Las actualizaciones descomprimen archivos y crean temporales; perderán esa pelea.

Decisión: Libera espacio antes de reintentar actualizaciones. Eliminar .maintenance puede restaurar el sitio brevemente, pero lo volverás a romper la próxima vez que WordPress intente escribir.

Task 10: Inspecciona el directorio de trabajo de upgrade

cr0x@server:~$ sudo ls -la /var/www/html/wp-content/upgrade
total 12
drwxr-xr-x  3 www-data www-data 4096 Dec 27 09:01 .
drwxr-xr-x 11 www-data www-data 4096 Dec 27 09:01 ..
drwx------  4 www-data www-data 4096 Dec 27 09:01 plugin-temp-ABcD12

Qué significa: WordPress usa wp-content/upgrade para extracción temporal. Directorios sobrantes pueden indicar una actualización interrumpida.

Decisión: No borres a ciegas. Primero restaura la disponibilidad del sitio y luego limpia tras confirmar qué falló.

Task 11: Valida la propiedad y permisos de archivos (ruptura común tras “endurecimiento” de seguridad)

cr0x@server:~$ sudo stat -c '%U:%G %a %n' /var/www/html/wp-content /var/www/html/wp-content/plugins
root:root 755 /var/www/html/wp-content
root:root 755 /var/www/html/wp-content/plugins

Qué significa: Propiedad por root, no por el usuario web. Si WordPress se ejecuta como www-data, puede que no pueda escribir actualizaciones, borrar .maintenance o crear temporales.

Decisión: Corrige la propiedad para que coincida con tu modelo de ejecución (a menudo www-data:www-data en Debian/Ubuntu). Si usas un usuario de despliegue con grupo con permiso de escritura + setgid, hazlo intencionadamente—no improvises.

Task 12: Elimina .maintenance (solo tras las comprobaciones)

cr0x@server:~$ sudo rm -f /var/www/html/.maintenance && sudo ls -la /var/www/html/.maintenance
ls: cannot access '/var/www/html/.maintenance': No such file or directory

Qué significa: El archivo de bloqueo ya no existe.

Decisión: Vuelve a probar el sitio desde el origen de inmediato. Si sigue mostrando mantenimiento, estás tratando con cacheo u otro mecanismo diferente.

Task 13: Confirma que el sitio volvió (y si está realmente sano)

cr0x@server:~$ curl -sS -D- -o /dev/null https://example.com/ | sed -n '1,10p'
HTTP/2 200
date: Sat, 27 Dec 2025 10:19:44 GMT
content-type: text/html; charset=UTF-8
server: nginx

Qué significa: HTTP 200. El banner de mantenimiento no se está sirviendo.

Decisión: Ahora revisa wp-admin y los logs. Un 200 puede seguir siendo un tema roto que renderiza un esqueleto HTML triste.

Task 14: Comprueba la salud de WordPress con WP-CLI (si está disponible)

cr0x@server:~$ cd /var/www/html && sudo -u www-data wp core version
6.4.3

Qué significa: WP-CLI puede ejecutarse y el core es legible. Buen indicador.

Decisión: Usa WP-CLI para terminar actualizaciones de forma limpia en lugar de hacer clic en wp-admin durante un incidente.

Task 15: Comprueba si hay actualizaciones de core/plugin/tema pendientes o a medio hacer

cr0x@server:~$ cd /var/www/html && sudo -u www-data wp plugin status | sed -n '1,12p'
Plugin name  Status   Update  Version
akismet      active   none    5.3
foo-plugin   active   available 2.1.0
bar-plugin   inactive none    1.9

Qué significa: Al menos un plugin tiene actualización disponible; quizá fue el que falló.

Decisión: Si una actualización causó el incidente, actualiza de forma controlada (WP-CLI, un plugin a la vez), observando logs y espacio en disco.

Task 16: Intenta una actualización controlada de plugin (uno a la vez)

cr0x@server:~$ cd /var/www/html && sudo -u www-data wp plugin update foo-plugin
Downloading update from https://downloads.wordpress.org/plugin/foo-plugin.2.1.0.zip...
Unpacking the update...
Installing the latest version...
Removing the old version of the plugin...
Plugin updated successfully.

Qué significa: La ruta de actualización funciona de extremo a extremo: descarga, descomprime, reemplaza, limpia.

Decisión: Si esto falla (permisos, disco, red), corrige la causa subyacente antes de repetir. Repetir una actualización fallida es la forma de acabar con un directorio lleno de plugins medio extraídos y arrepentimiento.

Task 17: Si wp-admin está roto, desactiva rápido el plugin culpable

cr0x@server:~$ cd /var/www/html && sudo -u www-data wp plugin deactivate foo-plugin
Plugin 'foo-plugin' deactivated.

Qué significa: Has quitado el plugin del runtime sin borrar archivos.

Decisión: Usa la desactivación como palanca de seguridad. Borrar directorios de plugins bajo presión es la manera de crear errores fatales por archivos faltantes si los autoloaders esperan archivos que desaparecen a mitad de petición.

Task 18: Si no tienes WP-CLI, haz una comprobación mínima del sistema de ficheros por plugins medio instalados

cr0x@server:~$ sudo find /var/www/html/wp-content/plugins -maxdepth 2 -type f -name '*.php' | head
/var/www/html/wp-content/plugins/akismet/akismet.php
/var/www/html/wp-content/plugins/foo-plugin/foo-plugin.php
/var/www/html/wp-content/plugins/bar-plugin/bar.php

Qué significa: Los archivos principales de los plugins existen. Si falta el archivo principal de un plugin, probablemente sea una instalación rota.

Decisión: Si un plugin está medio instalado, reinstálalo de forma limpia desde una fuente conocida (o restaura desde backup). No “parchees” archivos aleatorios faltantes.

Por qué se queda atascado: modos de fallo que puedes comprobar

El modo mantenimiento atascado es un síntoma. La enfermedad suele ser una de estas:

1) Actualización interrumpida (timeouts, procesos terminados, reinicios)

Las actualizaciones de WordPress son una secuencia de escrituras: descargar zip, desempaquetar en temp, reemplazar archivos, ejecutar rutinas de actualización, borrar .maintenance. Si PHP agota tiempo, FPM se reinicia, el contenedor se redeploya o el host se reinicia en el momento equivocado, la limpieza puede no ejecutarse nunca. El sitio queda bloqueado porque el archivo de bloqueo sigue ahí.

Puntos de prueba: logs de errores mostrando fatales/timeouts en update.php, restos en wp-content/upgrade, y una marca temporal de .maintenance que coincide con la ventana del último deploy/reinicio.

2) Disco lleno (o agotamiento de inodos)

Las actualizaciones escriben mucho. No son escrituras grandes—muchas pequeñas. Un sistema de ficheros casi lleno causa fallos impredecibles: la extracción de zip falla, no se pueden crear directorios temporales, y WordPress puede no ser capaz de eliminar .maintenance aunque la actualización “casi” haya tenido éxito.

Puntos de prueba: df -h por encima de 95%, errores ENOSPC en logs, y a veces el primo más molesto: agotamiento de inodos en sistemas con millones de archivos pequeños.

3) Desajuste de permisos / propiedad

El proceso web debe poder escribir en ciertas rutas durante las actualizaciones. Algunos equipos endurecen permisos tras una revisión de seguridad y luego olvidan que WordPress no es un generador estático de sitios. Si wp-content es propiedad de root y no escribible por el usuario de runtime, WordPress puede crear .maintenance en un contexto y no poder borrarlo después.

Puntos de prueba: stat muestra propietarios desajustados, errores tipo “Could not create directory” y la interfaz de actualización pidiendo credenciales FTP (una reliquia que aparece cuando las escrituras directas al sistema de ficheros fallan).

4) Capas de caché sirviendo mantenimiento obsoleto

Has eliminado .maintenance, actualizas y el banner sigue ahí. Entonces recuerdas que tienes: CDN, caché de proxy inverso, caché de objetos, plugin de caché de páginas, caché de navegador y tal vez un worker de borde “optimizando” HTML. Cualquiera de ellos puede cachear un 503 y seguir sirviéndolo.

Puntos de prueba: el origen devuelve 200 mientras el borde devuelve 503; las cabeceras difieren entre origen y borde; purgar la caché lo arregla inmediatamente.

5) La actualización “tuvo éxito” pero el runtime está roto

A veces el modo mantenimiento se quita correctamente, pero el sitio sigue caído por un error fatal introducido por la actualización: versión de PHP incompatible, extensiones faltantes, conflictos entre plugins, problemas con el tema. El banner de mantenimiento fue solo un indicador de que estabas en la vía de actualización.

Puntos de prueba: errores fatales de PHP tras eliminar el archivo, wp-admin inaccesible y logs mostrando funciones/clases faltantes vinculadas a código de plugin/tema.

Broma corta #1: El modo mantenimiento de WordPress es como una nota adhesiva en la puerta que dice “Vuelvo en 1 minuto.” Nunca es un minuto.

Errores comunes: síntoma → causa raíz → solución

Esta sección existe porque la gente sigue cometiendo las mismas tres cosas malas: adivinar, apresurarse y “optimizar” sin rollback.

El banner de mantenimiento persiste incluso después de borrar .maintenance

• Síntoma: .maintenance ya no existe, pero los usuarios siguen viendo la página de mantenimiento.
• Causa raíz: Respuesta cacheada (CDN, proxy inverso, plugin de caché de páginas) o borraste el .maintenance del sitio equivocado (docroot erróneo).
• Solución: Verifica la respuesta del origen con curl al origen, confirma el docroot correcto vía configuración de vhost, purga la caché de borde si es necesario.

El sitio devuelve 500 tras eliminar .maintenance

• Síntoma: El modo mantenimiento desaparece, pero ahora hay un 500 o una página en blanco.
• Causa raíz: La actualización dejó un plugin/tema medio actualizado; mismatch de versión de PHP; extensión faltante; mapa de autoload corrupto.
• Solución: Revisa los logs de error; desactiva plugins sospechosos (WP-CLI o renombrando directorio); reinstala el plugin/tema afectado de forma limpia; confirma versión/extensiones de PHP.

El modo mantenimiento vuelve inmediatamente después de eliminarlo

• Síntoma: Borras .maintenance, refrescas y vuelve a aparecer.
• Causa raíz: Un proceso de actualización sigue en marcha (cron, auto-updates, otra sesión admin) y recrea el archivo.
• Solución: Para la actividad de actualización (pausa pipeline de despliegue, desactiva auto-actualizaciones temporalmente, investiga cron), luego elimina el archivo cuando el sistema esté estable.

Las actualizaciones siempre fallan y dejan modo mantenimiento

• Síntoma: Es un patrón, no un incidente aislado. Cada actualización arriesga tiempo de inactividad.
• Causa raíz: Sistema de ficheros no escribible para el usuario de runtime; presión de disco; salida de red bloqueada a endpoints de descarga; herramientas de seguridad reescribiendo permisos.
• Solución: Arregla el modelo de ejecución: usuario/grupo consistente, rutas de upgrade escribibles, espacio libre suficiente en disco, permitir salida a fuentes de actualización y deja de “endurecer” con chmod al azar.

wp-admin pide credenciales FTP durante actualizaciones

• Síntoma: La interfaz de actualización pide credenciales FTP/SSH.
• Causa raíz: WordPress no puede escribir directamente en el sistema de ficheros (permisos/propiedad o sistema montado en solo lectura).
• Solución: Corrige propiedad/permisos y opciones de montaje. Si debes usar infraestructura inmutable, haz actualizaciones vía pipeline de compilación, no desde wp-admin.

Sólo algunas páginas muestran modo mantenimiento

• Síntoma: La página de inicio funciona, páginas específicas muestran mantenimiento (o al revés).
• Causa raíz: Inconsistencia de caché (un nodo de caché tiene 503 obsoleto), o una página de mantenimiento generada por plugin es condicional.
• Solución: Purga caches globalmente; revisa múltiples POPs; verifica si un plugin de “modo mantenimiento” está habilitado.

Tres mini-historias del mundo corporativo

Mini-historia #1: El incidente causado por una suposición equivocada

Una compañía mediana ejecutaba WordPress detrás de un balanceador con dos nodos de app. Las actualizaciones eran “simples”: entrar en wp-admin, click en actualizar, esperar a que el spinner pare y seguir. Una mañana, marketing intentó actualizar un plugin cinco minutos antes de un lanzamiento. El sitio entró en modo mantenimiento y se quedó así.

El on-call borró .maintenance en el nodo A. Sin cambio. Lo borraron otra vez. Aún sin cambio. Entonces concluyeron que WordPress “estaba atascado en otra parte” y empezaron a reiniciar servicios.

La suposición equivocada: que había un único sistema de ficheros. En realidad, el nodo A y el nodo B tenían discos locales separados (sin almacenamiento compartido). El balanceador seguía enviando la mitad del tráfico al nodo B, donde .maintenance aún existía. Los usuarios vivían una ruleta: refresca y quizá obtienes el sitio; refresca y quizá obtienes mantenimiento.

Cuando entendieron que era un problema de consistencia multi-nodo, la solución fue poco glamorosa: eliminar .maintenance en ambos nodos, y dejar de hacer actualizaciones in-place en pets. Pasaron las actualizaciones de plugins a un paso de build con artefactos y desplegaron de forma consistente entre nodos.

La lección no es “usa almacenamiento compartido.” La lección es: conoce tu topología antes de hacer una reparación en un solo host sobre un sistema multi-host. Los sistemas distribuidos no premian el optimismo.

Mini-historia #2: La optimización que salió mal

Otra organización quería páginas más rápidas. Añadieron cache agresiva en el borde y la configuraron para cachear “errores por poco tiempo” para proteger el origen durante picos. Objetivo sensato. Predeterminado arriesgado.

Durante una actualización de core de WordPress, el sitio devolvió un 503 por unos 20 segundos. El borde lo cacheó. Los usuarios siguieron recibiendo la respuesta de mantenimiento mucho más tiempo que la ventana real de actualización, incluso después de que .maintenance se eliminara. Internamente, el equipo veía el sitio funcionando (porque evitaban el CDN en la red corporativa). Externamente, los clientes veían “Briefly unavailable.” Los tickets de soporte empezaron a multiplicarse como conejos con plan de proyecto.

Purgaron el borde y todo se recuperó al instante. Luego tuvieron que explicar por qué una actualización de 20 segundos causó una indisponibilidad mucho más larga. La acción post-incidente no fue “no cachees.” Fue: no cachear la respuesta de mantenimiento, no cachear 503s de rutas de WordPress y configurar reglas de bypass para /wp-admin/ y endpoints relacionados con actualizaciones.

Las optimizaciones de rendimiento son geniales hasta que hacen que tu modo de fallo sea pegajoso. En producción, “fallo pegajoso” es un tipo especial de caro.

Mini-historia #3: La práctica aburrida pero correcta que salvó el día

Un equipo empresarial ejecutaba WordPress como parte de una plataforma mayor. Nada sofisticado: Nginx, PHP-FPM, MariaDB, más un pipeline de despliegue que construía un artefacto para core y plugins aprobados. Los editores seguían usando wp-admin para contenido, pero las actualizaciones de código eran solo CI/CD.

Una tarde, un auto-update se activó por accidente en un plugin (una configuración cambió durante una migración). El plugin intentó actualizarse durante tráfico pico. Creó .maintenance y luego falló porque el sistema de ficheros era de solo lectura por diseño (despliegue-only).

El sitio entró en mantenimiento, pero el equipo tenía dos redes de seguridad: (1) un artefacto versionado y de solo lectura que garantizaba que la base de código fuera consistente, y (2) snapshots horarios que les permitían revertir instantáneamente si el sistema de ficheros era tocado. Eliminaron .maintenance, confirmaron que no se habían modificado archivos (porque no podían), desactivaron auto-actualizaciones de plugins y abrieron una solicitud de cambio para evitar esa deriva de configuración.

Sin heroísmos. Sin arqueología frenética por SSH. Solo límites claros: el runtime sirve, el pipeline escribe. No es emocionante, y ese es el punto.

Prevención: hazlo aburrido y dejará de ocurrir

El modo mantenimiento atascado suele ser un problema de procesos con disfraz de sistema de ficheros. Lo previenes haciendo que las actualizaciones sean predecibles y recuperables.

Prefiere actualizaciones controladas (WP-CLI o pipeline), no click-ops

Hacer click en “Update now” en wp-admin desde un portátil en un Wi‑Fi de cafetería no es una estrategia de despliegue. Es un ejercicio de confianza. Usa WP-CLI en el servidor o ejecuta actualizaciones en un pipeline que pueda reintentarse, registre y permita rollback.

Mantén margen de disco como si lo sintieras

Para hosts de WordPress, me gusta mantener al menos unos pocos GB libres en volúmenes pequeños y más en los grandes. Actualizaciones, caches, logs, subidas de imágenes y backups compiten por espacio. La presión de disco causa síntomas raros mucho antes de llegar al 100%.

Haz consistente la propiedad/permisos de archivos

Elige un modelo operativo y aplícalo:

• Modelo de servidor mutable: WordPress puede escribir actualizaciones. Entonces el usuario de runtime debe poseer o tener acceso de escritura a las rutas relevantes. Ideal para sitios pequeños; arriesgado para grandes.
• Modelo de despliegue inmutable: El runtime es de solo lectura; las actualizaciones se hacen en un paso de build. Ideal para fiabilidad; requiere disciplina.

Mezclar los dos modelos produce la situación clásica donde WordPress puede crear .maintenance pero no puede eliminarlo. Eso no es “seguridad.” Es una trampa que te pones a ti mismo.

Guardarraíles: monitores y alertas para modo mantenimiento

Añade una comprobación sintética que solicite tu página principal y falle si aparece el título de mantenimiento. Es una alerta de alta señal y bajo esfuerzo. Tus clientes no deben ser el sistema de monitoreo.

Reglas de caché: no permitas que “brevemente no disponible” se convierta en “cacheado permanentemente”

En tu CDN o proxy inverso, define un comportamiento sensato para respuestas 503 y para rutas de administración de WordPress. El modo mantenimiento es una respuesta transitoria que no debería ser cacheada ampliamente.

Broma corta #2: Nada dice “nivel empresarial” como cachear una página de error en 200 ubicaciones en todo el mundo.

Listas de verificación / plan paso a paso

Checklist A: Saca el sitio del modo mantenimiento de forma segura (10–15 minutos)

1. Confirma lo que ve el usuario (origen vs cache).
2. Localiza la raíz de WordPress correcta vía wp-config.php.
3. Comprueba existencia y marca temporal de .maintenance.
4. Busca actualizaciones activas (procesos, logs).
5. Revisa espacio en disco e inodos.
6. Revisa wp-content/upgrade por directorios temporales sobrantes.
7. Haz snapshot/backup si está disponible.
8. Elimina .maintenance.
9. Valida: página principal, un par de enlaces profundos, login en wp-admin.
10. Revisa logs para confirmar que no hay fatales/timeouts continuos.

Checklist B: Repara la falla subyacente de la actualización (30–90 minutos)

1. Arregla la presión de disco (limpia logs antiguos, directorios de caché, backups sin usar).
2. Corrige propiedad/permisos para que coincida con tu modelo.
3. Actualiza vía WP-CLI un componente a la vez.
4. Si un plugin/tema está corrupto, reinstálalo limpio.
5. Verifica que la versión de PHP y las extensiones cumplan los requisitos del plugin.
6. Ejecuta una prueba rápida y vigila los logs de error.

Checklist C: Prevenir repeticiones (aquí es donde los adultos justifican su salario)

1. Decide: WordPress mutable o despliegue con artefactos inmutables. Escríbelo.
2. Añade monitoreo sintético para la respuesta de mantenimiento.
3. Añade alertas de disco e inodos antes de llegar al problema.
4. Configura reglas de CDN/proxy para evitar cachear páginas 503 de mantenimiento.
5. Programa actualizaciones en horas de bajo tráfico con rutas de rollback claras.
6. Mantén backups/snapshots probados, no solo configurados.

Datos interesantes y contexto histórico

• El modo mantenimiento de WordPress se implementa como un simple archivo de bloqueo (.maintenance) en lugar de una bandera en la base de datos, lo que lo mantiene rápido e independiente del estado DB.
• El mensaje “Briefly unavailable…” existe desde muchas versiones mayores y perdura porque es fiable en condiciones de actualización parcial: si PHP puede leer un archivo, puede mostrar un mensaje.
• WP-CLI empezó como un proyecto comunitario y se convirtió en estándar de facto porque las actualizaciones por clic no escalan operativamente.
• Las actualizaciones automáticas en segundo plano se introdujeron para reducir el retraso en parches para lanzamientos de seguridad, pero también introdujeron un nuevo modo de fallo: actualizaciones desatendidas en sistemas de ficheros mal configurados.
• Las actualizaciones de WordPress funcionan extrayendo archivos ZIP en directorios temporales, lo que las hace sensibles al espacio en disco y a la disponibilidad de inodos.
• Muchos hosts habilitaban históricamente el flujo de “credenciales FTP” porque PHP a menudo corría como un usuario no privilegiado que no podía escribir en el directorio del sitio.
• Algunas capas de caché cachean 503s por defecto como medida de resiliencia, lo que puede extender involuntariamente la ventana visible de mantenimiento mucho más allá de la actualización real.
• El ecosistema de plugins crea complejidad operativa: una sola actualización de plugin puede cambiar requisitos de runtime (versión de PHP, extensiones), convirtiendo una actualización rutinaria en una caída.

Preguntas frecuentes

1) ¿Siempre es seguro borrar el archivo .maintenance?

Usualmente sí—si no hay una actualización en curso. Si una actualización sigue activa, borrarlo puede permitir tráfico contra un código medio actualizado. Revisa procesos/logs y la marca temporal primero.

2) ¿Dónde está ubicado el archivo .maintenance?

En el directorio raíz de WordPress (el mismo directorio que contiene wp-config.php). Si tienes sitios múltiples, cada uno tiene su propia raíz y su propio .maintenance.

3) ¿Por qué vuelve el modo mantenimiento después de eliminarlo?

Porque algo lo está recreando: un reintento de auto-actualización, un cron, o otra sesión admin intentando actualizaciones. Detén el disparador de la actualización y luego elimina el archivo.

4) Eliminé .maintenance y ahora tengo pantalla blanca. ¿Qué pasó?

La actualización probablemente introdujo un error fatal (incompatibilidad de plugin/tema, extensión PHP faltante, autoload roto). Revisa logs de PHP/Nginx/Apache y desactiva el plugin sospechoso o cambia de tema.

5) ¿Puede una caché hacer parecer que WordPress sigue en modo mantenimiento?

Absolutamente. Los CDNs y proxies inversos pueden cachear la respuesta de mantenimiento. Compara respuestas origen vs borde; purga caches si el origen está sano.

6) ¿Cuál es la forma más rápida de desactivar plugins si wp-admin está caído?

WP-CLI es lo más rápido: wp plugin deactivate --all (luego reactivas selectivamente). Sin WP-CLI, renombrar el directorio del plugin puede funcionar, pero es más brusco y menos auditable.

7) ¿El modo mantenimiento de WordPress afecta solo el frontend?

Puede afectar tanto frontend como admin, dependiendo de la ruta de la petición y del momento. Durante actualizaciones, a menudo no puedes usar wp-admin de forma fiable hasta que la actualización termine o se quite el bloqueo.

8) ¿Cómo prevengo esto en futuras actualizaciones?

Arregla las causas raíz: asegura espacio en disco adecuado, permisos consistentes y un método de actualización controlado (WP-CLI o pipeline). También configura caches para evitar cachear respuestas 503 de mantenimiento.

9) ¿Debo borrar el contenido de wp-content/upgrade?

Después de restaurar el servicio y confirmar que no hay una actualización en curso, puedes eliminar directorios temporales antiguos en wp-content/upgrade. Si dudas, déjalo hasta haber reparado la actualización; puede ser evidencia.

10) ¿Y si estoy en un entorno multi-nodo?

Revisa cada nodo que pueda servir el sitio. Si el almacenamiento no es compartido, cada nodo puede tener su propio .maintenance. También asegúrate de que no se intenten actualizaciones de forma independiente en múltiples nodos.

Conclusión: siguientes pasos para reducir el tiempo de inactividad

Cuando WordPress está atorado en modo mantenimiento, la solución mecánica es borrar .maintenance. La solución profesional es asegurarte de que no estás interrumpiendo una actualización activa, luego reparar la razón subyacente por la que se atascó.

Haz lo siguiente:

1. Verifica origen vs caché y purga solo cuando hayas probado que el cacheo es el problema.
2. Revisa espacio en disco y permisos—dos problemas aburridos que causan la mayor parte del drama.
3. Termina las actualizaciones con WP-CLI (una a la vez) o mueve las actualizaciones a un pipeline.
4. Añade monitoreo para la respuesta de mantenimiento para que lo detectes antes que tus clientes.

Haz que las actualizaciones sean aburridas, repetibles y observables. WordPress seguirá encontrando formas de sorprenderte—pero menos de ellas ocurrirán a las 9:01 del día de lanzamiento.