Diagnosing Missing Vendor Prefixes in PostCSS Autoprefixer Builds

Recognizable Condition

The compiled CSS output lacks expected vendor prefixes such as -webkit-, -moz-, or -ms- for modern features like display: flex, CSS grid, transitions, or gradient backgrounds. This results in broken layouts or missing animations in older browsers.

Cause / Diagnostic Table

Possible Cause	What to Look For
Autoprefixer plugin missing or disabled in PostCSS config	PostCSS configuration does not list autoprefixer in the plugins array, or it is commented out.
Browserslist query returns no target browsers	The browserslist field (in package.json or a .browserslistrc file) evaluates to an empty set for the current environment.
Source CSS uses non‑standard syntax that Autoprefixer cannot parse	Custom properties, unsupported at‑rules, or syntax errors prevent Autoprefixer from recognizing the feature.
Autoprefixer runs after a minifier or cssnano step	In the plugin list, a minifier appears before autoprefixer, causing prefixes to be stripped.

Ordered Checks

1. Verify PostCSS plugin list

   Open the PostCSS configuration file (commonly postcss.config.js or postcss.config.cjs). Ensure the autoprefixer plugin is present and enabled.

   module.exports = {
     plugins: [
       require('autoprefixer'),
       // other plugins …
     ]
   };

2. Inspect browserslist configuration

   Check where browserslist is defined (package.json under "browserslist", a .browserslistrc file, or environment variable). Run npx browserslist to see the resolved list.

   # Example: see which browsers are targeted
   npx browserslist
   

   If the output is empty or does not include the versions you need, adjust the query.

3. Confirm source CSS uses standard syntax

   Look at the source file being processed. Ensure features like display: flex are written without vendor prefixes and that there are no syntax errors (e.g., missing semicolons).

4. Check plugin order relative to minifiers

   In the same PostCSS config, verify that autoprefixer appears before any CSS minifier such as cssnano or purgecss.

   module.exports = {
     plugins: [
       require('autoprefixer'),
       require('cssnano')({ preset: 'default' })
     ]
   };

Fixes Tied to Findings

• If Autoprefixer is missing: Add it to the plugins array and reinstall if needed (npm i -D autoprefixer).
• If browserslist yields no targets: Edit the browserslist configuration to include at least one version, e.g., "last 2 versions" or 0.2% and not dead". Then re‑run the build.
• If source syntax is problematic: Correct any CSS errors or replace unsupported at‑rules with standard equivalents before the PostCSS step.
• If Autoprefixer is after a minifier: Reorder the plugins so autoprefixer precedes the minifier, then rebuild.

Escalation Criteria

If after performing the above checks and fixes the compiled CSS still lacks prefixes:

• Enable verbose PostCSS logging to confirm which plugins are executed and in what order (POSTCSS_LOG=level npm run build).
• Compare the output against a baseline generated with a known‑good browserslist (e.g., "last 2 versions") using a diff tool.
• Check for custom PostCSS plugins or transforms that might strip or alter prefixes after Autoprefixer (e.g., a custom postcss-plugin that rewrites properties).
• If the issue persists, consider isolating the problem by creating a minimal reproduction repository and consulting the Autoprefixer issue tracker with the exact PostCSS and browserslist versions.

Verification

After applying a fix, inspect the generated CSS for the expected prefixes:

• Search for -webkit-flex, -moz-flex, or -ms-flex in the output.
• For gradients, verify presence of -webkit-linear-gradient or similar.
• Use a browser’s developer tools to confirm that the prefixed rules apply in the targeted older browser version.

Limitations: Autoprefixer only adds prefixes for features it knows about; very new or experimental CSS may not be prefixed until a newer version of the plugin is released. Always keep autoprefixer and browserslist up to date.