The css-loader schema validation error is one of the most common Webpack build failures — it fires before compilation even starts and gives you an error path that looks cryptic until you know how to read it. This guide explains exactly what triggers these errors, how to decode the message, which webpack.config.js changes fix each case, and how to validate your config so the next build succeeds on the first attempt.
What is a schema validation error?
Webpack validates every loader's options object against a JSON schema before it starts compiling. This schema defines which properties are allowed, what types they accept, and which values are valid. When your configuration passes a property that the schema does not recognise — or passes the wrong type for a known property — Webpack throws a schema validation error and refuses to build.
Why validation happens before compilation
Webpack validates upfront because loader options affect how files are processed. An invalid option could silently produce wrong output if Webpack ignored it, so strict validation at startup is the safer design. The trade-off is a hard stop before any code is touched — but the error message always tells you exactly which option is wrong and where it lives in your config tree.
The error format
A css-loader schema validation error follows a predictable structure. It always includes the loader name (css-loader), the path to the offending option in your config object (e.g. options.localIdentName), the specific problem (`unknown property, should be one of the allowed values, or should be [type]`), and often a link to the loader's documentation. Reading the path first is always the fastest route to the fix.
Note
Why css-loader triggers them
css-loader has gone through significant option schema changes across its major versions. Developers who upgrade css-loader — or copy a webpack.config.js from a tutorial targeting a different version — frequently end up with options that were valid in an older release but are now unknown or restructured.
All CSS Modules options have been moved under the modules option to avoid top-level option pollution and improve schema clarity.
The v4 breaking change
The most common source of css-loader schema errors is the v3 → v4 migration. In css-loader v3, CSS Modules options sat at the top level of the options object: localIdentName, camelCase, minimize, and modules as a boolean. In v4, all CSS Modules options moved into a dedicated modules sub-object, and minimize was removed entirely (CSS minification now belongs to css-minimizer-webpack-plugin). Any project still using the v3 flat-option syntax with a v4+ installation triggers an immediate schema validation error.
Other common triggers
- Typos in option names — moduls instead of modules, localIdentiyName instead of localIdentName
- Wrong value type — passing a string where an object is required, or a number where a boolean is expected
- Removed options — minimize (removed in v4), importLoaders as a boolean (must be a number), camelCase (removed in v6)
- Copying configs from wrong version tutorials — Stack Overflow answers targeting css-loader v2 are still widely served by search engines
- Conflicting peer dependencies — a third-party package pins an older css-loader version that is incompatible with your config
Tip
Reading the error message
Every css-loader schema validation error contains the information you need to fix it — if you know how to read the path notation. The error message has three parts that matter: the loader name, the configuration path, and the specific problem description. Focus on them in that order.
Understanding the path notation
The path notation mirrors the structure of your webpack.config.js. A path like module.rules[0].use[1].options.localIdentName means: look at the module key, then rules, then the first array item (index 0), then use, then the second loader in that use array (index 1), then options, then the localIdentName property. Follow that path in your config file to find the exact line causing the error.
The three error subtypes
| Error subtype | Message contains | What it means | Fix |
|---|---|---|---|
| Unknown property | "has an unknown property" | Property does not exist in this version | Remove or rename the property |
| Wrong type | "should be a [type]" | Right property, wrong value type | Change the value to the correct type |
| Invalid value | "should be one of the allowed" | Right property, value not in allowed set | Use one of the listed valid values |
| Additional property | "additionalProperties is false" | Object has keys not in schema | Remove unlisted keys from the object |
The should be one of subtype always lists the valid options inline in the error. The unknown property subtype does not suggest alternatives — you need to check the current css-loader documentation for the property's new name or equivalent. Use the Webpack Config Validator to get all errors at once rather than discovering them one at a time through repeated builds.
Warning
How to fix css-loader errors
The fix is always a targeted change to the css-loader options object in your webpack.config.js. Work through these steps in order to resolve the error cleanly without introducing new ones.
Read the full error message and copy the path
Scroll past the stack trace to the ValidationError section and copy the full message. It names the loader (css-loader), the exact configuration path, and the problem. The path tells you which rules entry and which position in the use array contains the invalid options object.
Locate the rule in webpack.config.js
Find the module.rules entry that loads .css files. It typically looks like a test for .css files using style-loader and css-loader with an options object. The options object inside the css-loader entry is where all schema errors originate. Open that object and compare it against the list of valid options for your installed css-loader version.
Apply the correct fix for your error subtype
For an unknown property error: rename or move the property to its new location. localIdentName moves to modules.localIdentName. minimize is removed — install css-minimizer-webpack-plugin separately. camelCase is removed — use the exportLocalsConvention option in the modules object instead. For a wrong type error: convert modules: true to an object with mode: 'local' if you need CSS Modules configuration, or keep it as a boolean if you do not.
Validate the fixed config before rebuilding
Paste the updated webpack.config.js into the Webpack Config Validator to confirm all schema errors are resolved before running the full build. This catches any secondary errors introduced by the fix, saving another build cycle.
Webpack Config Validator
Paste your webpack.config.js and instantly validate all loader options — detects css-loader schema errors, invalid module rules, and output configuration mistakes before your next build.
Common css-loader config mistakes
These are the specific option errors that appear most frequently in css-loader schema validation failures. Each entry shows the broken config pattern, the correct replacement, and which css-loader version the change applies to.
localIdentName at the top level (v3 → v4)
In css-loader v3, localIdentName was a top-level option controlling CSS Modules class name generation. In v4+, it moved inside the modules object. The fix is to nest it inside modules with the localIdentName property set to your pattern. The error message says options has an unknown property 'localIdentName' — this is the number one css-loader migration error.
minimize option removed (v4+)
The minimize option was removed from css-loader in v4. CSS minification is now handled separately by css-minimizer-webpack-plugin in the optimization.minimizer array. Remove minimize from your css-loader options entirely and add css-minimizer-webpack-plugin to your build if minification is needed. The CSS Validator can help you verify the output CSS is correct after switching minification tools.
camelCase option removed (v6)
css-loader v6 removed the top-level camelCase option. The replacement is modules.exportLocalsConvention, which accepts camelCase, camelCaseOnly, dashes, or dashesOnly. Update your options to set exportLocalsConvention inside the modules object. Without this change, any v6 installation with the old camelCase property triggers an unknown property error.
| Old option (broken) | css-loader version | Correct replacement |
|---|---|---|
| options.localIdentName | v4+ | options.modules.localIdentName |
| options.minimize | v4+ | css-minimizer-webpack-plugin plugin |
| options.camelCase | v6+ | options.modules.exportLocalsConvention |
| options.modules: true | v4+ (for customisation) | options.modules: { mode: "local", ... } |
| options.importLoaders: true | all | options.importLoaders: 1 (number, not boolean) |
| options.sourceMap: "inline" | v4+ | options.sourceMap: true (boolean only) |
Note
Validating your webpack config
The most efficient way to resolve css-loader schema errors — especially after a major version upgrade — is to validate the entire webpack.config.js at once rather than discovering errors one build at a time. Several tools make this fast.
The Webpack Config Validator
The Webpack Config Validator accepts your full webpack.config.js and reports all schema violations across every loader, plugin, and top-level option in a single pass. It surfaces the same path notation Webpack uses in runtime errors, so you can cross-reference the output with the error you saw in your terminal. Paste your config, get all issues at once, fix them, and paste again to confirm — no build cycle required.
Checking the config file for JavaScript syntax errors first
If Webpack fails to even parse your webpack.config.js due to a JavaScript syntax error — mismatched braces, a missing comma, or an invalid spread — you will see a Node.js parse error rather than a schema validation error. Use the JavaScript Syntax Validator to rule out syntax issues before debugging schema validation.
Validating related config files
css-loader is rarely the only configuration file in a build pipeline. If you use PostCSS for transforms, the PostCSS Config Validator catches plugin ordering errors and missing dependencies in postcss.config.js. If you use stylelint for CSS quality checks, the Stylelint Config Validator validates your .stylelintrc before it interferes with the build. The ESLint Config Validator is useful if your build chain also runs ESLint — misconfigurations there can surface as build errors that look similar to loader errors.
PostCSS Config Validator
Validate postcss.config.js for plugin ordering and option errors — catches configuration issues that frequently pair with css-loader schema errors in complex Webpack setups.
css-loader with PostCSS and CSS Modules
Most production Webpack setups use css-loader alongside PostCSS and CSS Modules. Each adds its own options and its own potential schema errors. Understanding how they interact prevents the most common configuration conflicts.
The importLoaders option
When PostCSS runs on a CSS file before css-loader, you must set importLoaders: 1 (or higher) in css-loader's options to ensure that @import statements in the CSS are also processed by PostCSS. Without it, imported files skip PostCSS. A common mistake is setting importLoaders: true — this triggers a schema validation error because the option must be a number, not a boolean. Set it to the number of loaders that run before css-loader in the chain.
CSS Modules with custom class names
CSS Modules class name customisation moved to the modules sub-object in css-loader v4. A full CSS Modules configuration with a custom identity pattern uses mode, localIdentName, and exportLocalsConvention — each as a separate option with its own schema constraints. Passing any of them at the top level of options instead of inside modules produces an unknown property error.
url and import options
css-loader's url and import options control whether the loader resolves url() references and @import statements. Both accept either a boolean or a filter function object. Passing a plain function — rather than an object with a filter property — triggers a schema error because the option schema expects an object with a filter property, not a bare function. Always wrap filter functions in the expected object shape.
Warning
Key takeaways
- css-loader schema validation errors fire before compilation and always name the exact invalid option path — read the path first, not the stack trace.
- The most common cause is using css-loader v3 option syntax (flat localIdentName, minimize, camelCase) with a v4+ or v6+ installation.
- In css-loader v4+, all CSS Modules options move inside a modules sub-object — localIdentName becomes modules.localIdentName.
- minimize was removed in v4 — use css-minimizer-webpack-plugin in optimization.minimizer instead.
- importLoaders must be a number (e.g. 1), not a boolean — passing true triggers a type validation error.
- Use the Webpack Config Validator to catch all schema errors in one pass before rebuilding.
- Check related configs too — PostCSS, ESLint, and Stylelint misconfigurations frequently accompany css-loader errors in complex pipelines.