Tecnología · GUÍA PRÁCTICA
¿Docker no encuentra un ayudante de credenciales? Rastrea la configuración, el binario y el proceso
Demuestra qué configuración eligió qué docker-credential-*, y si el mismo usuario, WSL, sudo o servicio puede ejecutarlo antes de desactivar el almacén.
El error nombra un programa, no una contraseña dañada: Docker eligió un ayudante como docker-credential-desktop o docker-credential-gcloud, pero el proceso que inició Docker no pudo ejecutarlo. Borrar config.json o escribir mal credsStore puede ocultar la llamada y también desactivar el almacén seguro previsto.
Conserva el archivo, identifica la configuración y la entrada de registro que Docker usó, convierte el sufijo en docker-credential-<sufijo> y comprueba su visibilidad desde el mismo usuario, shell, sudo, WSL o servicio. Repara solo el límite cuya falla puedas demostrar.
Fija el proceso llamador y la configuración efectiva
Anota el comando y registro exactos que fallan, junto con whoami, HOME, DOCKER_CONFIG, el shell o servicio y el uso de sudo o WSL. Copia config.json a un respaldo privado antes de editar; no publiques auth, tokens ni salidas del ayudante.
Inspecciona solo la estructura no secreta: primero credHelpers para el registro objetivo y después credsStore. Si ejecuta root, un servicio u otro usuario de Windows/WSL, revisa el archivo de ese proceso.
Traduce el valor a un solo ejecutable
Si credHelpers asigna gcloud al objetivo, el comando esperado es docker-credential-gcloud; si credsStore vale desktop, es docker-credential-desktop. El sufijo es el programa literal que Docker intenta ejecutar, no un paquete adivinado.
Usa command -v, type -a o el equivalente desde el mismo contexto. Si falta, distingue un puente obsoleto de Docker Desktop de un ayudante independiente configurado antes de instalar, copiar o enlazar nada.
Separa el fallo de PATH del fallo interno
Ejecuta una comprobación documentada que no revele secretos, como versión o lista. Si una prueba oficial get devuelve Secret, trátalo como dato sensible y no lo guardes en registros compartidos.
Si el shell no inicia el ayudante, repara instalación o PATH. Si inicia y falla el llavero, pass, gpg, el puente Desktop o la autenticación cloud, deja de cambiar Docker y diagnostica ese ayudante.
Repara el límite mínimo demostrado
Una clave o sufijo erróneo exige una edición estrecha; un ayudante oficial ausente exige restaurar ese binario; una diferencia entre usuario, root, WSL o servicio exige alinear HOME, DOCKER_CONFIG y PATH del proceso real.
No renombres credsStore a credStore como arreglo permanente. Esta última no es una clave válida y Docker la ignora. Elimina o sustituye el almacén solo si eliges deliberadamente otro diseño documentado.
Repite la ruta original y define el éxito
Inicia una instancia nueva del mismo shell, servicio, trabajo CI o WSL y repite el comando Docker contra el mismo registro. Hay éxito cuando desaparece el error, se alcanza el almacén previsto y no intervino por accidente otro usuario o archivo.
Si se resuelve una copia inesperada, la configuración se regenera o el error solo vuelve con sudo o automatización, detente y compara otra vez el inventario del llamador. No borres credenciales hasta conocer el propietario y ayudante admitido.
