Problemas con asdf (y cómo los resolví)

Hoy más que compartir una reflexión, quiero documentar una solución que he tenido que aplicar recientemente, por si tú también te topas con el mismo muro, tengas una guía rápida que te ayude.

No he encontrado demasiada información al respecto, así que espero que este post te ahorre unas cuantas búsquedas, frustración y pruebas a ciegas.

Contexto: qué es asdf y por qué lo uso

Desde hace unos años uso asdf para gestionar distintas versiones de herramientas de desarrollo, especialmente Node.js. Es una solución multi-plataforma, extensible y bastante popular entre quienes trabajamos con múltiples entornos.

Si no la conoces, echa un vistazo a su documentación oficial.

Actualizando a asdf 0.16: promesas y realidades

Hace poco actualicé a la versión 0.16, que venía con una re-escritura profunda del core en Go. En teoría, mejoras de rendimiento y fiabilidad. En la práctica… mi entorno dejó de funcionar como debía.

Lo que me encontré:

• asdf no reconocía correctamente las versiones instaladas.
• Al ejecutar un shim (como node, npm, etc.), recibía errores diciendo que no encontraba el binario.

La documentación oficial no fue suficiente

Empecé por el camino obvio: la guía oficial de migración a 0.16. Es clara y cubre varios puntos clave, pero en mi caso seguía sin funcionar.

La pista clave

Después de mucho rebuscar, encontré este post que, aunque hablaba de otro problema, me hizo mirar hacia un punto crítico:

~/.asdf/shims

Por algún motivo, aunque seguía los pasos indicados en la guía de migración, regenerar los shims no era suficiente. Había que eliminarlos manualmente antes de regenerarlos.

La solución

rm -rf ~/.asdf/shims
asdf reshim

Una vez hecho esto, asdf volvió a comportarse como debía.

¿Mi recomendación? Espera antes de actualizar

A fecha de abril de 2025, momento en el que escribo este post y tras pelearme con esta migración, mi recomendación es no dar aún el salto a la 0.16, salvo que tengas una necesidad muy concreta.

En este post te he hablado de cómo solucionar un problema concreto con el que me encontré, pero sigo teniendo que lidiar con algunas funcionalidades algo inestables.

En mi experiencia, la versión 0.15 sigue siendo más estable, especialmente si usas asdf en entornos productivos o CI/CD.

Gracias por leer. Como has visto, este post ha sido bastante diferente a lo que tengo acostumbrado pero creo que en ocasiones es útil compartir "tips" extraídos de mi trabajo en las trincheras. Si te ha resultado útil, compártelo. Recuerda además que puedes añadir tus comentarios a través de LinkedIn y/o Mastodon.