When you see the warning:

“When linting something other than CSS, you should install an appropriate syntax, e.g. postcss-scss, and use the customSyntax option”

it’s Stylelint telling you: “I’m only set up to understand plain CSS, but you’re giving me SCSS/Less/another syntax, so you must plug in the right parser and point me to it.”

Below is a clear breakdown of what that means and how to fix it, plus some context you can reuse in a blog/forum post.

What the warning really means

Stylelint’s core understands standard CSS.

When you lint something other than plain CSS (for example):

  • SCSS (.scss)
  • Sass (indented)
  • Less (.less)
  • SugarSS
  • CSS-in-JS or HTML with embedded styles

then Stylelint needs a custom syntax (in PostCSS terms, a parser) to understand that language’s extra features and syntax.

That’s why the message tells you to:

  • Install the right PostCSS syntax package, e.g. postcss-scss for SCSS.
  • Configure Stylelint to use it via the customSyntax option.

The core rule: “install syntax + use customSyntax”

For SCSS, the pattern looks like this:

  1. Install the syntax:

    bash

npm install --save-dev postcss-scss

  2. In your Stylelint config (e.g. stylelint.config.js), wire it up:

    js

export default {
  overrides: [
    {
      files: ["**/*.scss"],
      customSyntax: "postcss-scss",
      extends: ["stylelint-config-standard-scss"],
      rules: {
        "at-rule-no-unknown": null,
        "scss/at-rule-no-unknown": true,
        // other rules…
      },
    },
  ],
};

Here is what’s happening conceptually:

 * `customSyntax: "postcss-scss"` tells Stylelint: _“parse these files with the SCSS-aware PostCSS syntax.”_

 * `extends: ["stylelint-config-standard-scss"]` brings in SCSS-friendly defaults and SCSS-specific rules.

 * `"at-rule-no-unknown": null` \+ `"scss/at-rule-no-unknown": true` turn off the generic CSS rule and turn on the SCSS-aware one, so `@mixin`, `@include`, etc. are correctly recognized.

The same idea applies to other syntaxes:

  • Less → install postcss-less, then set customSyntax: "postcss-less".
  • SugarSS → install sugarss, then set customSyntax: "sugarss".
  • A custom or exotic language → write or use a PostCSS syntax and point customSyntax to it.

When not to use customSyntax: PostCSS plugin mode

There is one important nuance: when you are running Stylelint as a PostCSS plugin in a PostCSS pipeline , the syntax is controlled by PostCSS itself, not by customSyntax.

In that case, you do something like:

js

const fs = require("fs");
const less = require("postcss-less");
const postcss = require("postcss");

const code = fs.readFileSync("input.less", "utf8");

postcss([
  require("stylelint")({
    /* stylelint options here, but no customSyntax */
  }),
  require("postcss-reporter")({ clearReportedMessages: true }),
])
  .process(code, {
    from: "input.less",
    syntax: less, // PostCSS syntax object
  })
  .then(() => {})
  .catch((err) => console.error(err.stack));
  • In this mode, you use PostCSS’s syntax option (e.g. syntax: less), and you don’t configure customSyntax inside Stylelint.

Example: SCSS in VS Code / “standard” configs

A common modern setup (especially in editors like VS Code) is:

  • stylelint
  • stylelint-config-standard-scss
  • postcss-scss
  • An editor integration (e.g. the Stylelint extension)

If you forget to install postcss-scss, or forget to set customSyntax, you see the error:

When linting something other than CSS, you should install an appropriate syntax, e.g. "postcss-scss", and use the "customSyntax" option.

The fix:

  • Add postcss-scss as a dev dependency.
  • Add an overrides block to your config with customSyntax: "postcss-scss" for SCSS files.

How this ties into custom syntaxes in general

Stylelint’s docs treat “custom syntaxes” as PostCSS syntaxes written by the community to support things like SCSS, HTML containers, CSS-in-JS, or arbitrary new extensions.

The recommended pattern for any non-CSS file type is:

js

import yourCustomSyntax from "postcss-your-custom-syntax";

export default {
  overrides: [
    {
      files: ["*.foo", "**/*.foo"],
      customSyntax: yourCustomSyntax,
      extends: ["stylelint-config-standard"],
      rules: {
        "at-rule-no-unknown": null,
        // your rules here…
      },
    },
  ],
};
  • You scope the syntax to the relevant files pattern.
  • You can share this as a reusable config like stylelint-config-standard-foo if you want.

Mini “forum style” summary

Quick scoop:
If Stylelint complains that “when linting something other than CSS, you should install an appropriate syntax, e.g. postcss-scss, and use the customSyntax option,” it’s telling you that your current setup only knows how to read plain CSS, but you’re feeding it SCSS/Less/another syntax. The fix is always a two-step combo: install the right PostCSS syntax package for your language (postcss-scss, postcss-less, etc.) and then point Stylelint at it using customSyntax in your config (or syntax in PostCSS plugin mode).

SEO-style meta description idea:
Learn what the Stylelint warning “when linting something other than CSS, you should install an appropriate syntax, e.g. postcss-scss, and use the customSyntax option” really means, and how to correctly configure postcss- scss, customSyntax, and PostCSS syntax options to lint SCSS, Less, and other non-CSS styles reliably.

Information gathered from public forums or data available on the internet and portrayed here.