Si gestionas tus contenedores Docker mediante el plugin Compose en OpenMediaVault (OMV), es posible que tras una actualización del sistema te hayas encontrado con que Portainer deja de funcionar. El contenedor no arranca y, al revisar los logs, te encuentras con un error crítico de «API version».
Cabe mencionar que NO soy un experto en el tema, y me sirvo de las herramientas a mi alcance para conseguir solucionar este tipo de cosas.
En este artículo explicamos por qué sucede esto y cómo solucionarlo paso a paso.
1. El Problema: El error de «Client Version is too old»
El error suele presentarse con un mensaje similar a este:
FTL > failed initializing upgrade service | error="failed to determine container platform: ... client version 1.42 is too old. Minimum supported API version is 1.44"¿Por qué ocurre?
Este fallo sucede porque el motor de Docker en tu servidor se ha actualizado (probablemente a la versión 26 o 27), la cual requiere una versión de la API de Docker mínima (1.44). Si estás intentando ejecutar una imagen de Portainer antigua o la versión obsoleta (portainer/portainer), el cliente interno de Portainer no sabe «hablar» con el nuevo motor de Docker.
2. La Solución: Actualizar a Portainer CE
La solución definitiva consiste en migrar a la imagen oficial mantenida:
portainer/portainer-cePaso 1: Editar el archivo Docker Compose
Desde el panel de OMV, ve a Servicios > Compose > Files, selecciona tu stack de Portainer y pulsa Editar. Debes asegurarte de que tu configuración sea similar a esta:
services:
portainer:
image: portainer/portainer-ce:latest # Usar siempre la Community Edition
container_name: portainer-ce # Cambiamos el nombre si el anterior da conflicto
restart: unless-stopped
security_opt:
– no-new-privileges:true
volumes:
– /etc/localtime:/etc/localtime:ro
– /var/run/docker.sock:/var/run/docker.sock:ro
– ./data:/data # Persistencia de datos
ports:
– 9443:9443 # Acceso seguro vía HTTPS
Paso 2: Resolver conflictos de nombre
Si al intentar levantar el contenedor recibes un error de «Conflict. The container name is already in use», Docker tiene un contenedor «zombi» bloqueando el nombre. Tienes dos opciones:
- Limpieza por SSH: Ejecuta $
docker rm -f portainerpara borrar el contenedor antiguo. He usado Putty, recuerda que el usuario con el que inicies sesión debe tener permisos SUDO y _SSH, esto lo ocnfiguras dentro del OMV en USERS. - Renombrado rápido: Cambia el
container_nameen tu YAML (por ejemplo, deportaineraportainer-ce), como hicimos en el ejemplo anterior.
3. Aplicar los cambios en OpenMediaVault
Una vez editado el archivo, muchos usuarios cometen el error de pulsar directamente el botón «Up». Sin embargo, si quieres solucionar el error de la API, el orden de los factores sí altera el producto. Sigue estos pasos:
- Save: Guarda los cambios en el editor. Esto registra tu nueva configuración en la base de datos de OMV.
- Pull (CRUCIAL): Haz clic en el botón de descarga (icono de la flecha hacia abajo ⬇️).
- ¿Por qué es vital? Docker es ahorrador por naturaleza; si ya tiene una imagen llamada
portainer-ce:latesten tu disco (aunque sea antigua), no irá a buscar una nueva. Al pulsar Pull, fuerzas a OMV a conectar con internet y descargar los parches de compatibilidad necesarios para la API de Docker 1.44+.
- ¿Por qué es vital? Docker es ahorrador por naturaleza; si ya tiene una imagen llamada
- Up: Una vez finalizada la descarga, pulsa el botón de arranque (icono de la flecha hacia arriba ⬆️). Esto creará el nuevo contenedor utilizando la imagen que acabas de descargar.
💡 Consejo: Si después de hacer el Pull y el Up el sistema sigue quejándose del nombre en uso, recuerda usar el comando
docker rm -f portainerpor SSH o cambiar elcontainer_nameen el archivo como vimos en el paso anterior.
4. Acceso y Verificación
Al haber configurado el puerto 9443, el acceso ahora es exclusivamente a través de protocolo seguro:
- URL:
https://IP-DE-TU-SERVIDOR:9443 - Aviso de Seguridad: Tu navegador mostrará un aviso de «Conexión no privada». Esto es normal al usar certificados locales. Haz clic en Opciones avanzadas > Acceder (sitio no seguro).
¿Se pierden los datos?
Si en la sección de volumes apuntaste correctamente a la carpeta donde tenías los datos antiguos (por ejemplo ./data:/data), Portainer reconocerá tus contenedores y configuraciones anteriores automáticamente. Es posible que te pida crear un usuario administrador de nuevo si la base de datos es detectada como nueva, pero una vez dentro, verás todo tu entorno de Docker intacto.
Una vez accedas al nuevo PORTAINER CE, debrías poder ver los CONTENDORES que tenías, y … el «Zombi» que nos estaba molestando:
Conclusión
Mantener las imágenes actualizadas (:latest) y usar la rama correcta (portainer-ce) es vital en sistemas como OpenMediaVault que actualizan el motor de Docker con frecuencia. Con estos pasos, habrás recuperado el control de tu panel de gestión sin perder tus contenedores actuales.
Puntos clave incluidos
- ✅ Causa Raíz: Explicación clara de la API 1.42 vs 1.44.
- ✅ La Solución de Imagen: Cambio de
portainer/portaineraportainer/portainer-ce. - ✅ El Conflicto de Nombres: Solución mediante el renombrado del
container_name. - ✅ El Puerto HTTPS: Recordatorio de usar
https://y el puerto9443. - ✅ Persistencia: Confirmación de que los contenedores previos se mantienen.
⚠️ Nota importante sobre el primer acceso: Por seguridad, Portainer cierra el asistente de configuración si no creas el usuario administrador en los primeros 5 minutos tras el arranque. Si al intentar entrar te sale un mensaje de error diciendo que «por seguridad se ha cerrado el asistente», simplemente vuelve a OpenMediaVault y pulsa el botón Restart en tu stack de Portainer para reiniciar el temporizador.
⚠️ Nota importante al finalizar: recuerda seactivar el acceso por SSH si no lo usas, para así evitar problemas de accesos no deseados.
⚠️ Nota importante Final: NO me hago respnsable de nada, si has seguido esta guía es bajo tu responsabilidad.
¿Te ha servido este tutorial? No olvides compartirlo con otros usuarios de OMV que puedan estar sufriendo este bloqueo tras actualizar sus sistemas.