Stylelint "Unknown rule" in CI

By Daniel Zoghalchali·Latchkey

Stylelint validates every rule name in the config against its built-in rules and registered plugins. "Unknown rule" means a rule was renamed, removed, or belongs to a plugin that is not loaded.

What this error means

Stylelint exits non-zero with "Unknown rule selector-no-empty" (or another rule) instead of linting, naming the rule it does not recognize.

Unknown rule scss/at-rule-no-unknown.

Error: Unknown rule scss/at-rule-no-unknown.
    at /home/runner/work/app/app/node_modules/stylelint/lib/...

Common causes

The rule belongs to an uninstalled plugin

A namespaced rule like scss/at-rule-no-unknown requires stylelint-scss in the plugins array; without it the rule is unknown.

The rule was removed or renamed in a Stylelint major

Upgrading Stylelint can remove or rename rules, so a config carried over references a name that no longer exists.

How to fix it

Install and register the plugin

1. Identify the plugin that provides the namespaced rule.
2. Install it and add it to the plugins array.
3. Re-run Stylelint.

npm install --save-dev stylelint-scss

Update or remove a removed rule

For a renamed or removed built-in, replace it with its current name or drop it, per the Stylelint changelog.

// .stylelintrc.json
{ "plugins": ["stylelint-scss"], "rules": { "scss/at-rule-no-unknown": true } }

How to prevent it

• Install and register the plugin for every namespaced rule.
• Review the Stylelint migration guide when upgrading majors.
• Run Stylelint in CI so unknown rules surface on PRs.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation