Error de permisos en var y generated de Magento 2: solución

El error de permisos en las carpetas var y generated de Magento 2 ocurre cuando el servidor web o el usuario del CLI no tienen privilegios de escritura sobre estos directorios de trabajo. La solución pasa por asignar el usuario correcto al propietario del sistema de archivos y aplicar la máscara de permisos recomendada por Adobe. Ajustar la propiedad y ejecutar el comando de permisos adecuado resolverá el problema de inmediato.

Qué significa el error

Este fallo aparece habitualmente con mensajes como The var directory is not writable o Permission denied al intentar escribir en generated/code o var/cache. Afecta tanto al panel de administración como al front-end, provocando pantallas en blanco (HTTP 500) o excepciones de tipo Local File. Ocurre porque Magento 2 necesita generar clases proxy, interceptores y caché en tiempo de ejecución, y el sistema operativo deniega la acción.

Causas más habituales

Ejecutar comandos del CLI de Magento (bin/magento) como usuario root en lugar del usuario del servidor web.
Despliegue de código o subida de archivos mediante FTP/SSH con un usuario distinto a www-data, apache o nginx.
Configuración incorrecta del grupo de usuarios de Linux (falta de pertenencia compartida entre el usuario del servidor y el usuario de despliegue).
Valores de umask restrictivos en el archivo app/etc/env.php o en la configuración del servidor.
Restricciones adicionales causadas por SELinux o AppArmor en distribuciones como RHEL, CentOS o Ubuntu Server.

Antes de empezar

Asegúrate de contar con acceso SSH como superusuario (sudo) al servidor donde está instalado Magento 2 (probado en Ubuntu 22.04 y 24.04 LTS con Magento 2.4.x y PHP 8.1 o 8.2). Es imprescindible identificar qué usuario ejecuta el servidor web (por ejemplo, www-data en Debian/Ubuntu o nginx/apache en RHEL/CentOS) y cuál es el usuario propietario de los archivos.

Solución 1: Asignar el propietario y grupo de usuarios correctos

Esta es la solución más limpia y duradera. Funciona porque garantiza que tanto el usuario que ejecuta PHP en el servidor web como el usuario que ejecuta comandos por consola pertenezcan al mismo grupo con permisos de escritura compartidos.

Accede a tu servidor mediante SSH y navega hasta la raíz de la instalación de Magento 2:
```
cd /var/www/html/magento2
```
Identifica el usuario del servidor web comprobando los procesos activos de PHP-FPM o Apache:
```
ps aux | grep -E 'apache|nginx|php'
```
Añade tu usuario del sistema (por ejemplo, magento_user) al grupo del servidor web (por ejemplo, www-data):
```
sudo usermod -aG www-data magento_user
```
Cambia el propietario y el grupo de todo el directorio de Magento 2 de forma recursiva:
```
sudo chown -R magento_user:www-data .
```
Cierra la sesión SSH y vuelve a entrar para que los cambios de grupo surtan efecto.

Solución 2: Aplicar la estructura recomendada de chmod

Si los usuarios ya están bien configurados pero los archivos creados tienen permisos demasiado restrictivos, debes aplicar los permisos estándar recomendados por la documentación oficial. Esto otorga acceso de lectura y ejecución a los directorios y de lectura y escritura a los archivos necesarios.

Desde la raíz de Magento 2, establece permisos 770 para directorios (lectura, escritura y ejecución para propietario y grupo):
```
find var generated vendor pub/static pub/media app/etc -type d -exec chmod 770 {} +
```

Establece permisos 660 para los archivos contenidos en estas carpetas:

find var generated vendor pub/static pub/media app/etc -type f -exec chmod 660 {} +

Otorga permisos de ejecución al ejecutable del CLI de Magento:
```
chmod u+x bin/magento
```

Esta solución funciona porque restablece la capacidad de modificación sobre las carpetas dinámicas de Magento sin comprometer la seguridad exponiendo carpetas a cualquier usuario del sistema (evitando el peligroso 777).

Solución 3: Eliminar el contenido generado y regenerar código

Si cambiaste los permisos pero sigues viendo errores de denegación de acceso, es probable que existan archivos creados previamente por root dentro de generated/ o var/ que bloqueen la sobrescritura. La solución es eliminar el contenido temporal y dejar que Magento lo vuelva a crear con el usuario adecuado.

Borra las carpetas de caché y código generado con privilegios elevados:

sudo rm -rf var/cache/* var/page_cache/* var/generation/* generated/code/* generated/metadata/*

Asegúrate de ejecutar la compilación de código usando el usuario correcto del sistema (nunca como root):
```
php bin/magento setup:di:compile
```
Si se producen errores durante este proceso, revisa si necesitas solucionar un error de compilación en Magento 2 antes de continuar.
Limpia la caché de Magento:
```
php bin/magento cache:clean
```

Solución 4: Configurar umask en app/etc/env.php

Si el problema reaparece cada vez que ejecutas la reindexación o el cron, se debe a que Magento crea nuevos archivos con una máscara de permisos predeterminada demasiado restrictiva. Cambiar el umask en el archivo de configuración corrige el comportamiento en origen.

Abre el archivo de configuración de Magento en tu editor de texto:
```
nano app/etc/env.php
```
Busca o añade la clave backend_register_umask dentro del array de configuración y establece el valor 002 o 007:
```
'backend_register_umask' => '002',
```
Guarda los cambios presionando Ctrl + O y sal con Ctrl + X.
Limpia la caché para que el cambio surta efecto:
```
php bin/magento cache:flush
```

Al configurar el umask en 002, los nuevos archivos creados por procesos en segundo plano tendrán automáticamente permisos 664 y las carpetas 775, lo que permite al grupo del servidor web escribir en ellos sin bloqueos.

Cómo comprobar que se ha solucionado

Para verificar la solución, navega por el front-end de la tienda y accede al panel de administración (Admin Panel). Abre la consola SSH y ejecuta un comando de mantenimiento con tu usuario normal:

php bin/magento cache:status

Si el comando devuelve la lista de cachés sin lanzar ninguna excepción de tipo Permission Denied y puedes guardar cambios en productos desde el panel de control, la configuración de permisos es óptima.

Si nada de lo anterior funciona

Si los permisos vuelven a cambiarse solos periódicamente, revisa la configuración del servicio cron del sistema. Es muy común que la tarea programada de Magento esté configurada en el crontab de root. Ejecuta sudo crontab -e y borra las líneas relativas a Magento; luego muévelas al crontab del usuario web ejecutando crontab -e -u www-data. Si estás usando SELinux en tu servidor Linux, puede que necesites cambiar el contexto de seguridad de los archivos mediante el comando chcon -R -t httpd_sys_rw_content_t var/ generated/.

Preguntas frecuentes

¿Es seguro usar chmod 777 en las carpetas var y generated?

No. Asignar permisos 777 permite que cualquier usuario o proceso del servidor lea, escriba y ejecute archivos en tu instalación. Esto representa un riesgo severo de seguridad en entornos de producción. Utiliza siempre la combinación de usuario/grupo compartida con permisos 770 o 775.

¿Por qué aparece el error tras ejecutar comandos con el CLI?

Aparece porque ejecutaste el comando bin/magento como usuario root o mediante sudo. Al hacerlo, los archivos resultantes en generated/ o var/ pasan a ser propiedad de root, impidiendo que el proceso PHP-FPM de la web pueda modificarlos.

¿Debo aplicar estos cambios en la carpeta pub/static?

Sí, las carpetas pub/static y pub/media requieren los mismos permisos de escritura que var y generated. Si estas carpetas no tienen permisos correctos, los archivos CSS, JavaScript e imágenes de la tienda no se desplegarán y la web perderá el formato gráfico.

¿Qué hago si mi proveedor de hosting no permite modificar el grupo www-data?

En alojamientos compartidos o administrados donde no tienes acceso a sudo, debes asegurarte de que tanto el servidor web como SSH operen bajo el mismo usuario local asignado a tu cuenta de cPanel o Plesk. Aplica permisos 755 a carpetas y 644 a archivos desde el administrador de archivos.