ZSH es increíblemente poderoso y personalizable, especialmente cuando lo combinas con frameworks como Oh My Zsh. Sin embargo, su configuración (el famoso archivo .zshrc) a veces puede romperse o generar mensajes de error extraños al abrir la terminal. Hoy te enseño cómo solucionar los tres dolores de cabeza más comunes de ZSH.

1. El infame: "command not found: compdef"

Este es probablemente el error más común para quienes instalan plugins manualmente o añaden autocompletados (como los de nvm, docker o git) a su .zshrc.

¿Por qué pasa? El sistema de autocompletado de ZSH (compinit) no se ha cargado antes de que un plugin intente usar la función compdef.

La solución: Debes asegurarte de inicializar el sistema de autocompletado antes de cargar tus plugins que dependan de él. Abre tu ~/.zshrc y añade estas líneas justo antes de donde te da el error (o al inicio del bloque de plugins):

autoload -Uz compinit
compinit

2. Historial corrupto: "zsh: corrupt history file"

Abres tu terminal y de repente ZSH se niega a guardar comandos nuevos o te lanza este error. Ocurre cuando la terminal se cierra de golpe o hay problemas de escritura en disco.

¿Por qué pasa? El archivo ~/.zsh_history tiene caracteres nulos o malformados y ZSH no puede leerlo.

La solución: Tienes que extraer las partes legibles del historial y crear un archivo nuevo. Ejecuta estos comandos línea por línea:

cd ~
mv .zsh_history .zsh_history_bad
strings .zsh_history_bad > .zsh_history
fc -R .zsh_history

El comando strings extrae solo el texto legible del archivo dañado y reconstruye un historial sano. ¡Magia pura!

3. Errores de permisos con insecure directories

A veces ves un bloque gigante de texto diciendo: "zsh compinit: insecure directories, run compaudit for list".

¿Por qué pasa? ZSH es muy estricto con la seguridad. Si carpetas como /usr/local/share/zsh/site-functions tienen permisos muy abiertos (ej. 777), ZSH se negará a cargar autocompletados desde allí para prevenir inyecciones de código.

La solución: Tienes que corregir los permisos de las carpetas de autocompletado. Ejecuta:

chmod -R 755 /usr/local/share/zsh/site-functions
chown -R root:root /usr/local/share/zsh/site-functions

Nota: Si usas macOS y Homebrew, podrías necesitar cambiar el propietario a tu usuario (chown -R $(whoami) ...).

Conclusión

ZSH es una herramienta que requiere un poco de cariño. La próxima vez que veas un error en la terminal, no lo ignores con un clear. Entender estos mensajes te ayuda a conocer más a fondo tu sistema Linux o macOS.