Compartir comentarios
Las respuestas se generan en base a la documentación.

Temas de resolución de problemas para Docker Desktop

Tabla de contenidos
Tip

Si no encuentras una solución en la resolución de problemas, explora los repositorios de GitHub o crea un nuevo problema.

Temas para todas las plataformas

Certificados no configurados correctamente

Mensaje de error

Al intentar descargar desde un registro utilizando docker run, es posible que encuentres el siguiente error:

Error response from daemon: Get http://192.168.203.139:5858/v2/: malformed HTTP response "\x15\x03\x01\x00\x02\x02"

Además, los logs del registro pueden mostrar:

2017/06/20 18:15:30 http: TLS handshake error from 192.168.203.139:52882: tls: client didn't provide a certificate
2017/06/20 18:15:30 http: TLS handshake error from 192.168.203.139:52883: tls: first record does not look like a TLS handshake

Causas posibles

  • Docker Desktop ignora los certificados listados bajo registros inseguros.
  • Los certificados de cliente no se envían a los registros inseguros, lo que provoca fallos en el acuerdo de conexión (handshake).

Solución

  • Asegúrate de que tu registro esté configurado correctamente con certificados SSL válidos.
  • Si tu registro es autofirmado, configura Docker para que confíe en el certificado añadiéndolo al directorio de certificados de Docker (/etc/docker/certs.d/ en Linux).
  • Si el problema persiste, comprueba la configuración de tu demonio de Docker y habilita la autenticación TLS.

La interfaz de usuario de Docker Desktop se muestra verde, distorsionada o con artefactos visuales

Causa

Docker Desktop utiliza gráficos acelerados por hardware por defecto, lo que puede causar problemas con algunas GPUs.

Solución

Desactiva la aceleración por hardware:

  1. Edita el archivo settings-store.json de Docker Desktop. Puedes encontrar este archivo en:

    • Mac: ~/Library/Group Containers/group.com.docker/settings-store.json
    • Windows: C:\Users\[USERNAME]\AppData\Roaming\Docker\settings-store.json
    • Linux: ~/.docker/desktop/settings-store.json.

  2. Añade la siguiente entrada:

    "disableHardwareAcceleration": true

  3. Guarda el archivo y reinicia Docker Desktop.

Al utilizar volúmenes montados se producen errores de ejecución indicando que no se encuentra un archivo de la aplicación, se deniega el acceso a un montaje de volumen o un servicio no puede iniciarse

Causa

Si el directorio de tu proyecto se encuentra fuera de tu directorio de usuario (/home/<user>), Docker Desktop requiere permisos de uso compartido de archivos para acceder a él.

Solución

Activa el uso compartido de archivos en Docker Desktop para Mac y Linux:

  1. Ve a Settings, selecciona Resources y luego File sharing.
  2. Añade la unidad o carpeta que contiene el Dockerfile y las rutas de montaje de volumen.

Activa el uso compartido de archivos en Docker Desktop para Windows:

  1. Desde Settings, selecciona Shared Folders.
  2. Comparte la carpeta que contiene el Dockerfile y las rutas de montaje de volumen.

Errores de tipo port already allocated (puerto ya asignado)

Mensaje de error

Al iniciar un contenedor, es posible que veas un error como:

Bind for 0.0.0.0:8080 failed: port is already allocated

O bien

listen tcp:0.0.0.0:8080: bind: address is already in use

Causa

  • Otra aplicación en tu sistema ya está utilizando el puerto especificado.
  • Un contenedor en ejecución anterior no se detuvo correctamente y todavía está vinculado al puerto.

Solución

Para descubrir la identidad de este software, puedes:

  • Usar la interfaz gráfica resmon.exe, seleccionar Network y luego Listening Ports.
  • En PowerShell, usar netstat -aon | find /i "listening " para descubrir el PID del proceso que utiliza actualmente el puerto (el PID es el número en la columna de la extrema derecha).

Luego, decide si cerrar el otro proceso o utilizar un puerto diferente en tu aplicación de Docker.

Temas para Linux y Mac

Docker Desktop no se inicia en plataformas Mac o Linux

Mensaje de error

Docker no se inicia debido a las limitaciones de longitud de la ruta del socket de dominio Unix:

[vpnkit-bridge][F] listen unix <HOME>/Library/Containers/com.docker.docker/Data/http-proxy-control.sock: bind: invalid argument

[com.docker.backend][E] listen(vsock:4099) failed: listen unix <HOME>/Library/Containers/com.docker.docker/Data/vms/0/00000002.00001003: bind: invalid argument

Causa

En Mac y Linux, Docker Desktop crea sockets de dominio Unix que se utilizan para la comunicación entre procesos. Estos sockets se crean bajo el directorio de usuario.

Los sockets de dominio Unix tienen una longitud de ruta máxima:

  • 104 caracteres en Mac
  • 108 caracteres en Linux

Si la ruta de tu directorio de usuario es demasiado larga, Docker Desktop no podrá crear los sockets necesarios.

Solución

Asegúrate de que tu nombre de usuario sea lo suficientemente corto como para mantener las rutas dentro del límite permitido:

  • Mac: El nombre de usuario debe ser ≤ 33 caracteres
  • Linux: El nombre de usuario debe ser ≤ 55 caracteres

Temas para Mac

La actualización requiere privilegios de administrador

Causa

En macOS, los usuarios sin privilegios de administrador no pueden realizar actualizaciones desde el panel de Docker Desktop.

Solución

Important

No desinstales la versión actual antes de actualizar. Si lo haces, se eliminarán todos los contenedores, imágenes y volúmenes locales de Docker.

Para actualizar Docker Desktop:

  • Pide a un administrador que instale la versión más reciente sobre la existente.
  • Utiliza la bandera de instalación --user si es adecuada para tu configuración (consulta Instalación en Mac).

Notificación persistente que indica que una aplicación ha cambiado mis configuraciones de Desktop

Causa

Recibes esta notificación porque la función de comprobación de integridad de la configuración ha detectado que una aplicación de terceros ha alterado tu configuración de Docker Desktop. Esto suele suceder debido a enlaces simbólicos incorrectos o faltantes. La notificación garantiza que estés al tanto de estos cambios para que puedas revisar y reparar cualquier problema potencial para mantener la confiabilidad del sistema.

Al abrir la notificación se presenta una ventana emergente que proporciona información detallada sobre los problemas de integridad detectados.

Solución

Si decides ignorar la notificación, se mostrará de nuevo únicamente en el siguiente inicio de Docker Desktop. Si decides reparar tu configuración, no se te volverá a preguntar.

Si deseas desactivar las notificaciones de comprobación de integridad de la configuración, ve a la configuración de Docker Desktop y, en la pestaña General, desactiva la opción Automatically check configuration.

com.docker.vmnetd sigue ejecutándose después de salir de la aplicación

El proceso auxiliar con privilegios com.docker.vmnetd es iniciado por launchd y se ejecuta en segundo plano. El proceso no consume recursos a menos que Docker.app se conecte a él, por lo que es seguro ignorarlo.

Se detectó una CPU incompatible

Causa

Docker Desktop requiere un procesador (CPU) que admita virtualización y, específicamente, el Apple Hypervisor framework.

Solución

Comprueba que:

  • Has instalado el Docker Desktop correcto para tu arquitectura.

  • Tu Mac es compatible con el framework Hypervisor de Apple. Para verificar si tu Mac admite el framework Hypervisor, ejecuta el siguiente comando en una ventana de la terminal:

    $ sysctl kern.hv_support

    Si tu Mac admite el framework Hypervisor, el comando mostrará kern.hv_support: 1.

    De lo contrario, el comando mostrará kern.hv_support: 0.

Consulta también la Referencia del Framework Hypervisor en la documentación de Apple, y los Requisitos del sistema para Mac de Docker Desktop.

Temas para Windows

Docker Desktop no se inicia cuando hay un software antivirus instalado

Causa

Algunos programas antivirus pueden ser incompatibles con Hyper-V y las compilaciones de Microsoft Windows. El conflicto suele ocurrir después de una actualización de Windows y se manifiesta como una respuesta de error del demonio de Docker y un fallo al iniciar Docker Desktop.

Solución

Como solución temporal, desinstala el software antivirus o añade Docker a las exclusiones/excepciones de tu software antivirus.

Errores de permisos en directorios de datos para volúmenes compartidos

Causa

Al compartir archivos desde Windows, Docker Desktop establece los permisos en los volúmenes compartidos a un valor predeterminado de 0777 (permisos de lectura, escritura y ejecución para el usuario y el grupo).

Los permisos predeterminados en los volúmenes compartidos no son configurables.

Solución

Si estás trabajando con aplicaciones que requieren permisos diferentes, puedes:

  • Utilizar volúmenes que no estén montados en el host.
  • Encontrar una forma de hacer que las aplicaciones funcionen con los permisos de archivo predeterminados.

Errores de sintaxis inesperados, utiliza saltos de línea de estilo Unix para los archivos en contenedores

Causa

Los contenedores de Docker esperan saltos de línea de estilo Unix \n, no de estilo Windows \r\n. Esto incluye los archivos referenciados en la línea de comandos para las construcciones y en las instrucciones RUN de los archivos Docker.

Ten esto en cuenta al crear archivos como scripts de shell utilizando herramientas de Windows, donde el valor predeterminado suele ser saltos de línea de estilo Windows. Estos comandos finalmente se pasan a comandos de Unix dentro de un contenedor basado en Unix (por ejemplo, un script de shell pasado a /bin/sh). Si se utilizan saltos de línea de estilo Windows, docker run falla con errores de sintaxis.

Solución

  • Convierte los archivos a saltos de línea de estilo Unix utilizando:

    $ dos2unix script.sh

  • En VS Code, establece los saltos de línea en LF (Unix) en lugar de CRLF (Windows).

Errores de conversión de rutas en Windows

Causa

A diferencia de Linux, Windows requiere una conversión de ruta explícita para el montaje de volúmenes.

En Linux, el sistema se encarga de montar una ruta en otra ruta. Por ejemplo, al ejecutar el siguiente comando en Linux:

$ docker run --rm -ti -v /home/user/work:/work alpine

Añade un directorio /work al contenedor de destino para reflejar la ruta especificada.

Solución

Actualiza la ruta de origen. Por ejemplo, si estás utilizando la consola heredada de Windows (cmd.exe), puedes utilizar el siguiente comando:

$ docker run --rm -ti -v C:\Users\user\work:/work alpine

Esto inicia el contenedor y garantiza que el volumen sea utilizable. Esto es posible porque Docker Desktop detecta la ruta de estilo Windows y proporciona la conversión adecuada para montar el directorio.

Docker Desktop también te permite utilizar rutas de estilo Unix con el formato adecuado. Por ejemplo:

$ docker run --rm -ti -v /c/Users/user/work:/work alpine ls /work

Fallo de comandos de Docker en Git Bash

Mensaje de error

$ docker run --rm -ti -v C:\Users\user\work:/work alpine
docker: Error response from daemon: mkdir C:UsersUserwork: Access is denied.

$ docker run --rm -ti -v $(pwd):/work alpine
docker: Error response from daemon: OCI runtime create failed: invalid mount {Destination:\Program Files\Git\work Type:bind Source:/run/desktop/mnt/host/c/Users/user/work;C Options:[rbind rprivate]}: mount destination \Program Files\Git\work not absolute: unknown.

Causa

Git Bash (o MSYS) proporciona un entorno similar a Unix en Windows. Estas herramientas aplican su propio preprocesamiento en la línea de comandos.

Esto afecta a $(pwd), las rutas separadas por dos puntos y la tilde (~).

Además, el carácter \ tiene un significado especial en Git Bash.

Solución

  • Desactiva temporalmente la conversión de rutas de Git Bash. Por ejemplo, ejecuta el comando con la conversión de rutas de MSYS desactivada:
    $ MSYS_NO_PATHCONV=1 docker run --rm -ti -v $(pwd):/work alpine
  • Utiliza el formato de ruta adecuado:
    • Utiliza barras diagonales dobles (\\ //) en lugar de simples (\ /).
    • Si haces referencia a $(pwd), añade una barra adicional /:

La portabilidad de los scripts no se ve afectada, ya que Linux trata múltiples / como una sola entrada.

Docker Desktop falla debido a que la virtualización no funciona

Mensaje de error

Un mensaje de error típico es "Docker Desktop - Unexpected WSL error" que menciona el código de error Wsl/Service/RegisterDistro/CreateVm/HCS/HCS_E_HYPERV_NOT_INSTALLED. La ejecución manual de comandos de wsl también falla con el mismo código de error.

Causa

  • Los ajustes de virtualización están desactivados en la BIOS.
  • Faltan componentes de Windows Hyper-V o WSL 2.

Ten en cuenta que algunos programas de terceros, como los emuladores de Android, desactivarán Hyper-V al instalarse.

Soluciones

Tu máquina debe contar con las siguientes características para que Docker Desktop funcione correctamente:

WSL 2 y Windows Home
  1. Plataforma de máquina virtual
  2. Subsistema de Windows para Linux (WSL)
  3. Virtualización activada en la BIOS. Ten en cuenta que muchos dispositivos Windows ya tienen la virtualización activada por defecto, por lo que esto podría no ser necesario.
  4. Hipervisor activado al inicio de Windows
WSL 2 activado

Debe ser posible ejecutar comandos de WSL 2 sin errores, por ejemplo:

PS C:\users\> wsl -l -v
  NAME              STATE           VERSION
* Ubuntu            Running         2
  docker-desktop    Stopped         2
PS C:\users\> wsl -d docker-desktop echo WSL 2 is working
WSL 2 is working

Si las funciones están activadas pero los comandos no funcionan, comprueba primero que la virtualización esté activada y luego activa el hipervisor al inicio de Windows si es necesario. Si estás ejecutando Docker Desktop en una máquina virtual, asegúrate de que el hipervisor tenga activada la virtualización anidada.

Hyper-V

En Windows 10 Pro o Enterprise, también puedes usar Hyper-V con las siguientes funciones activadas:

  1. Hyper-V instalado y funcionando.
  2. Virtualización activada en la BIOS. Ten en cuenta que muchos dispositivos Windows ya tienen la virtualización activada por defecto, por lo que esto podría no ser necesario.
  3. Hipervisor activado al inicio de Windows
Hyper-V en las características de Windows

Docker Desktop requiere que Hyper-V, así como el módulo Hyper-V para Windows PowerShell, estén instalados y activados. El instalador de Docker Desktop los activa por ti.

Docker Desktop también necesita dos funciones de hardware de la CPU para utilizar Hyper-V: Virtualización y Traducción de direcciones de segundo nivel (SLAT), que también se denomina Indexación rápida de virtualización (RVI). En algunos sistemas, la virtualización debe estar activada en la BIOS. Los pasos necesarios varían según el fabricante, pero normalmente la opción de la BIOS se llama Virtualization Technology (VTx) o algo similar. Ejecuta el comando systeminfo para comprobar todas las funciones de Hyper-V requeridas. Consulta los Requisitos previos para Hyper-V en Windows 10 para obtener más detalles.

Para instalar Hyper-V manualmente, consulta Instalar Hyper-V en Windows 10. Se requiere reiniciar después de la instalación. Si instalas Hyper-V sin reiniciar, Docker Desktop no funcionará correctamente.

Desde el menú de inicio, escribe Activar o desactivar las características de Windows y presiona enter. En la siguiente pantalla, verifica que Hyper-V esté activado.

La virtualización debe estar activada

Además de Hyper-V o WSL 2, la virtualización debe estar activada. Comprueba la pestaña de Rendimiento en el Administrador de tareas. Alternativamente, puedes escribir systeminfo en tu terminal. Si ves Requisitos de Hyper-V: Se ha detectado un hipervisor. No se mostrarán las características necesarias para Hyper-V, entonces la virtualización está activada.

Administrador de tareas

Si desinstalas manualmente Hyper-V, WSL 2 o desactivas la virtualización, Docker Desktop no podrá iniciarse.

Para activar la virtualización anidada, consulta Ejecutar Docker Desktop para Windows en un entorno de VM o VDI.

Hipervisor activado al inicio de Windows

Si has completado los pasos anteriores y sigues teniendo problemas para iniciar Docker Desktop, esto podría deberse a que el hipervisor está instalado pero no se inicia durante el arranque de Windows. Algunas herramientas (como las versiones antiguas de VirtualBox) y los instaladores de videojuegos desactivan el hipervisor al arrancar. Para volver a activarlo:

  1. Abre una consola de comandos con privilegios de administrador.
  2. Ejecuta bcdedit /set hypervisorlaunchtype auto.
  3. Reinicia Windows.

También puedes consultar el artículo de Microsoft TechNet sobre la configuración de Code flow guard (CFG).

Activar la virtualización anidada

Si estás utilizando Hyper-V y recibes el siguiente mensaje de error al ejecutar Docker Desktop en un entorno VDI:

The Virtual Machine Management Service failed to start the virtual machine 'DockerDesktopVM' because one of the Hyper-V components is not running

Intenta activar la virtualización anidada.

Docker Desktop con contenedores de Windows falla con el mensaje "El medio está protegido contra escritura"

Mensaje de error

FSCTL_EXTEND_VOLUME \\?\Volume{GUID}: The media is write protected

Causa

Si encuentras fallos al ejecutar Docker Desktop con contenedores de Windows, podría deberse a una política de configuración específica de Windows: FDVDenyWriteAccess.

Esta política, cuando está activada, hace que Windows monte todas las unidades fijas que no estén cifradas con BitLocker como de solo lectura. Esto también afecta a los volúmenes de las máquinas virtuales y, como resultado, es posible que Docker Desktop no pueda iniciar o ejecutar contenedores correctamente porque requiere acceso de lectura y escritura a estos volúmenes.

FDVDenyWriteAccess es una configuración de Directiva de grupo de Windows que, cuando está activada, impide el acceso de escritura a las unidades de datos fijas que no están protegidas por BitLocker. Esto se utiliza a menudo en entornos conscientes de la seguridad, pero puede interferir con herramientas de desarrollo como Docker. En el registro de Windows se puede encontrar en HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Policies\Microsoft\FVE\FDVDenyWriteAccess.

Soluciones

Docker Desktop no admite la ejecución de contenedores de Windows en sistemas donde FDVDenyWriteAccess está activada. Esta configuración interfiere con la capacidad de Docker para montar volúmenes correctamente, lo cual es fundamental para el funcionamiento de los contenedores.

Para usar Docker Desktop con contenedores de Windows, asegúrate de que FDVDenyWriteAccess esté desactivada. Puedes verificar y cambiar esta configuración en el registro o a través del Editor de directivas de grupo local (gpedit.msc) en:

Configuración del equipo > Plantillas administrativas > Componentes de Windows > Cifrado de unidad BitLocker > Unidades de datos fijas > Denegar acceso de escritura a unidades fijas no protegidas por BitLocker

Note

La modificación de la configuración de la Directiva de grupo puede requerir privilegios de administrador y debe cumplir con las políticas de TI de tu organización. Si la configuración se restablece después de un tiempo, esto generalmente significa que fue anulada por la configuración centralizada de tu departamento de TI. Habla con ellos antes de realizar cualquier cambio.

Mensaje de error Docker Desktop Access Denied al iniciar Docker Desktop

Mensaje de error

Al iniciar Docker Desktop, aparece el siguiente error:

Docker Desktop - Access Denied

Causa

El usuario no forma parte del grupo docker-users, el cual es necesario para obtener los permisos correspondientes.

Solución

Si tu cuenta de administrador es diferente de tu cuenta de usuario, agrégala:

  1. Ejecuta Administración de equipos (Computer Management) como administrador.
  2. Ve a Usuarios y grupos locales > Grupos > docker-users.
  3. Haz clic derecho para añadir el usuario al grupo.
  4. Cierra la sesión y vuelve a iniciarla para que los cambios surtan efecto.