El error de validación de esquema de css-loader es uno de los fallos de compilación más comunes de Webpack: se dispara antes de que la compilación comience y te da una ruta de error que parece críptica hasta que sabes leerla. Esta guía explica exactamente qué desencadena estos errores, cómo decodificar el mensaje, qué cambios en webpack.config.js arreglan cada caso y cómo validar tu configuración para que la próxima compilación funcione al primer intento.
¿Qué es un error de validación de esquema?
Webpack valida el objeto de opciones de cada loader contra un esquema JSON antes de empezar a compilar. Este esquema define qué propiedades se permiten, qué tipos aceptan y qué valores son válidos. Cuando tu configuración pasa una propiedad que el esquema no reconoce — o pasa el tipo incorrecto para una propiedad conocida — Webpack lanza un error de validación de esquema y se niega a compilar.
Por qué la validación ocurre antes de la compilación
Webpack valida por adelantado porque las opciones de los loaders afectan cómo se procesan los archivos. Una opción inválida podría producir una salida incorrecta silenciosamente si Webpack la ignorara, así que la validación estricta al inicio es el diseño más seguro. La contrapartida es una parada total antes de tocar cualquier código, pero el mensaje de error siempre te dice exactamente qué opción está mal y dónde se encuentra en tu árbol de configuración.
El formato del error
Un error de validación de esquema de css-loader sigue una estructura predecible. Siempre incluye el nombre del loader (css-loader), la ruta de la opción problemática en tu objeto de configuración (p. ej. options.localIdentName), el problema específico (`propiedad desconocida, debe ser uno de los valores permitidos o debe ser [tipo]`) y, a menudo, un enlace a la documentación del loader. Leer primero la ruta es siempre el camino más rápido hacia la solución.
Note
Por qué css-loader los provoca
css-loader ha atravesado cambios significativos en su esquema de opciones a lo largo de sus versiones mayores. Los desarrolladores que actualizan css-loader — o copian un webpack.config.js de un tutorial orientado a otra versión — terminan frecuentemente con opciones que eran válidas en una versión anterior pero que ahora son desconocidas o han sido reestructuradas.
Todas las opciones de CSS Modules se han movido bajo la opción modules para evitar la contaminación de opciones de nivel superior y mejorar la claridad del esquema.
El cambio disruptivo de la v4
La fuente más común de errores de esquema de css-loader es la migración v3 → v4. En css-loader v3, las opciones de CSS Modules estaban en el nivel superior del objeto de opciones: localIdentName, camelCase, minimize y modules como booleano. En la v4, todas las opciones de CSS Modules se movieron a un sub-objeto modules dedicado, y minimize se eliminó por completo (la minificación de CSS ahora pertenece a css-minimizer-webpack-plugin). Cualquier proyecto que aún use la sintaxis plana de la v3 con una instalación v4+ desencadena un error de validación de esquema inmediato.
Otros desencadenantes comunes
- Errores tipográficos en nombres de opciones - moduls en vez de modules, localIdentiyName en vez de localIdentName
- Tipo de valor incorrecto - pasar una cadena donde se requiere un objeto, o un número donde se espera un booleano
- Opciones eliminadas - minimize (eliminada en v4), importLoaders como booleano (debe ser un número), camelCase (eliminada en v6)
- Copiar configuraciones de tutoriales de otra versión - las respuestas de Stack Overflow orientadas a css-loader v2 siguen apareciendo mucho en los buscadores
- Dependencias peer en conflicto - un paquete de terceros fija una versión antigua de css-loader incompatible con tu configuración
Tip
Leer el mensaje de error
Cada error de validación de esquema de css-loader contiene la información que necesitas para arreglarlo, si sabes leer la notación de rutas. El mensaje tiene tres partes que importan: el nombre del loader, la ruta de configuración y la descripción específica del problema. Céntrate en ellas en ese orden.
Entender la notación de rutas
La notación de rutas refleja la estructura de tu webpack.config.js. Una ruta como module.rules[0].use[1].options.localIdentName significa: mira la clave module, luego rules, luego el primer elemento del array (índice 0), luego use, luego el segundo loader de ese array use (índice 1), luego options y luego la propiedad localIdentName. Sigue esa ruta en tu archivo de configuración para encontrar la línea exacta que causa el error.
Los tres subtipos de error
| Subtipo de error | El mensaje contiene | Qué significa | Solución |
|---|---|---|---|
| Propiedad desconocida | "has an unknown property" | La propiedad no existe en esta versión | Elimina o renombra la propiedad |
| Tipo incorrecto | "should be a [type]" | Propiedad correcta, tipo de valor equivocado | Cambia el valor al tipo correcto |
| Valor inválido | "should be one of the allowed" | Propiedad correcta, valor fuera del conjunto permitido | Usa uno de los valores válidos listados |
| Propiedad adicional | "additionalProperties is false" | El objeto tiene claves que no están en el esquema | Elimina las claves no listadas del objeto |
El subtipo «debe ser uno de los permitidos» siempre lista las opciones válidas en línea dentro del error. El subtipo «propiedad desconocida» no sugiere alternativas: debes consultar la documentación actual de css-loader para el nuevo nombre o equivalente de la propiedad. Usa el Validador de Configuración Webpack para obtener todos los errores de una vez en lugar de descubrirlos uno a uno mediante compilaciones repetidas.
Warning
Cómo arreglar errores de css-loader
La solución siempre es un cambio puntual en el objeto de opciones de css-loader en tu webpack.config.js. Sigue estos pasos en orden para resolver el error limpiamente sin introducir otros nuevos.
Lee el mensaje de error completo y copia la ruta
Desplázate más allá del stack trace hasta la sección ValidationError y copia el mensaje completo. Nombra el loader (css-loader), la ruta exacta de configuración y el problema. La ruta te dice qué entrada de rules y qué posición del array use contiene el objeto de opciones inválido.
Localiza la regla en webpack.config.js
Encuentra la entrada module.rules que carga archivos .css. Normalmente parece un test para archivos .css que usa style-loader y css-loader con un objeto de opciones. El objeto de opciones dentro de la entrada de css-loader es donde se originan todos los errores de esquema. Abre ese objeto y compáralo con la lista de opciones válidas para tu versión instalada de css-loader.
Aplica la solución correcta para tu subtipo de error
Para un error de propiedad desconocida: renombra o mueve la propiedad a su nueva ubicación. localIdentName se convierte en modules.localIdentName. minimize se elimina: instala css-minimizer-webpack-plugin por separado. camelCase se elimina: usa la opción exportLocalsConvention en el objeto modules en su lugar. Para un error de tipo incorrecto: convierte modules: true en un objeto con mode: 'local' si necesitas configuración de CSS Modules, o déjalo como booleano si no.
Valida la configuración corregida antes de recompilar
Pega el webpack.config.js actualizado en el Validador de Configuración Webpack para confirmar que todos los errores de esquema están resueltos antes de ejecutar la compilación completa. Esto detecta cualquier error secundario introducido por el arreglo, ahorrando otro ciclo de compilación.
Validador de Configuración Webpack
Pega tu webpack.config.js y valida al instante todas las opciones de loaders: detecta errores de esquema de css-loader, reglas de módulo inválidas y errores de configuración de salida antes de tu próxima compilación.
Errores comunes de configuración de css-loader
Estos son los errores de opciones específicos que aparecen con más frecuencia en los fallos de validación de esquema de css-loader. Cada entrada muestra el patrón de configuración roto, el reemplazo correcto y a qué versión de css-loader aplica el cambio.
localIdentName en el nivel superior (v3 → v4)
En css-loader v3, localIdentName era una opción de nivel superior que controlaba la generación de nombres de clase de CSS Modules. En v4+, se movió dentro del objeto modules. La solución es anidarlo dentro de modules con la propiedad localIdentName establecida a tu patrón. El mensaje de error dice options has an unknown property 'localIdentName' — este es el error de migración de css-loader número uno.
Opción minimize eliminada (v4+)
La opción minimize se eliminó de css-loader en la v4. La minificación de CSS ahora se maneja por separado con css-minimizer-webpack-plugin en el array optimization.minimizer. Elimina minimize por completo de tus opciones de css-loader y añade css-minimizer-webpack-plugin a tu build si necesitas minificación. El Validador de CSS puede ayudarte a verificar que el CSS de salida es correcto tras cambiar de herramienta de minificación.
Opción camelCase eliminada (v6)
css-loader v6 eliminó la opción camelCase de nivel superior. El reemplazo es modules.exportLocalsConvention, que acepta camelCase, camelCaseOnly, dashes o dashesOnly. Actualiza tus opciones para establecer exportLocalsConvention dentro del objeto modules. Sin este cambio, cualquier instalación v6 con la vieja propiedad camelCase desencadena un error de propiedad desconocida.
| Opción antigua (rota) | Versión de css-loader | Reemplazo correcto |
|---|---|---|
| options.localIdentName | v4+ | options.modules.localIdentName |
| options.minimize | v4+ | plugin css-minimizer-webpack-plugin |
| options.camelCase | v6+ | options.modules.exportLocalsConvention |
| options.modules: true | v4+ (para personalizar) | options.modules: { mode: "local", ... } |
| options.importLoaders: true | todas | options.importLoaders: 1 (número, no booleano) |
| options.sourceMap: "inline" | v4+ | options.sourceMap: true (solo booleano) |
Note
Validar tu configuración de webpack
La forma más eficiente de resolver errores de esquema de css-loader — especialmente tras una actualización de versión mayor — es validar todo el webpack.config.js de una vez en lugar de descubrir errores de una compilación a otra. Varias herramientas lo hacen rápido.
El Validador de Configuración Webpack
El Validador de Configuración Webpack acepta tu webpack.config.js completo y reporta todas las violaciones de esquema de cada loader, plugin y opción de nivel superior en una sola pasada. Muestra la misma notación de rutas que Webpack usa en los errores de ejecución, así que puedes cruzar la salida con el error que viste en tu terminal. Pega tu configuración, obtén todos los problemas de una vez, arréglalos y pega de nuevo para confirmar — sin necesidad de ciclo de compilación.
Comprobar primero el archivo de configuración por errores de sintaxis JavaScript
Si Webpack ni siquiera logra parsear tu webpack.config.js por un error de sintaxis JavaScript — llaves desemparejadas, una coma faltante o un spread inválido — verás un error de parseo de Node.js en lugar de un error de validación de esquema. Usa el Validador de Sintaxis JavaScript para descartar problemas de sintaxis antes de depurar la validación de esquema.
Validar archivos de configuración relacionados
css-loader rara vez es el único archivo de configuración en un pipeline de build. Si usas PostCSS para transformaciones, el Validador de Configuración PostCSS detecta errores de orden de plugins y dependencias faltantes en postcss.config.js. Si usas stylelint para comprobaciones de calidad CSS, el Validador de Configuración Stylelint valida tu .stylelintrc antes de que interfiera con la compilación. El Validador de Configuración ESLint es útil si tu cadena de build también ejecuta ESLint — las mala configuraciones allí pueden manifestarse como errores de build que parecen errores de loader.
Validador de Configuración PostCSS
Valida postcss.config.js en busca de errores de orden de plugins y de opciones: detecta problemas de configuración que frecuentemente acompañan a los errores de esquema de css-loader en setups Webpack complejos.
css-loader con PostCSS y CSS Modules
La mayoría de los setups de Webpack en producción usan css-loader junto con PostCSS y CSS Modules. Cada uno añade sus propias opciones y sus propios errores de esquema potenciales. Entender cómo interactúan previene los conflictos de configuración más comunes.
La opción importLoaders
Cuando PostCSS se ejecuta sobre un archivo CSS antes de css-loader, debes establecer importLoaders: 1 (o superior) en las opciones de css-loader para asegurar que las sentencias @import del CSS también pasen por PostCSS. Sin ello, los archivos importados omiten PostCSS. Un error común es poner importLoaders: true — esto desencadena un error de validación de esquema porque la opción debe ser un número, no un booleano. Establécelo al número de loaders que se ejecutan antes de css-loader en la cadena.
CSS Modules con nombres de clase personalizados
La personalización de nombres de clase de CSS Modules se movió al sub-objeto modules en css-loader v4. Una configuración completa de CSS Modules con un patrón de identidad personalizado usa mode, localIdentName y exportLocalsConvention — cada uno como opción separada con sus propias restricciones de esquema. Pasar cualquiera de ellos en el nivel superior de options en lugar de dentro de modules produce un error de propiedad desconocida.
Opciones url e import
Las opciones url e import de css-loader controlan si el loader resuelve las referencias url() y las sentencias @import. Ambas aceptan un booleano o un objeto con función de filtro. Pasar una función pura — en lugar de un objeto con propiedad filter — desencadena un error de esquema porque el esquema de la opción espera un objeto con propiedad filter, no una función desnuda. Envuelve siempre las funciones de filtro en la forma de objeto esperada.
Warning
Key takeaways
- Los errores de validación de esquema de css-loader se disparan antes de la compilación y siempre nombran la ruta exacta de la opción inválida: lee primero la ruta, no el stack trace.
- La causa más común es usar la sintaxis de opciones de css-loader v3 (localIdentName plano, minimize, camelCase) con una instalación v4+ o v6+.
- En css-loader v4+, todas las opciones de CSS Modules se mueven dentro de un sub-objeto modules: localIdentName pasa a ser modules.localIdentName.
- minimize se eliminó en v4: usa css-minimizer-webpack-plugin en optimization.minimizer en su lugar.
- importLoaders debe ser un número (p. ej. 1), no un booleano: pasar true desencadena un error de validación de tipo.
- Usa el Validador de Configuración Webpack para detectar todos los errores de esquema en una sola pasada antes de recompilar.
- Revisa también las configuraciones relacionadas: las mala configuraciones de PostCSS, ESLint y Stylelint acompañan frecuentemente a los errores de css-loader en pipelines complejos.