We are running Magento 2 in version 2.3.1, but the error occurred in version 2.3.0 also. The situation is the following:

  • we've created a custom theme which has Magento/luma theme as parent.
  • according to https://devdocs.magento.com/guides/v2.3/frontend-dev-guide/css-topics/css_debug.html we've installed node and grunt for theme LESS development.
  • the grunt themes.js config of our custom child theme has files:['css/styles-m', 'css/styles-l', 'css/style'] entries. (where 'styles-m' and 'styles-l' are files from the parent, and 'css/style' is our custom LESS file)
  • our custom LESS file style.less is located in our custom VENDOR/THEME/web/css/ folder and is also registered as <css src="css/style.css" /> within default_head_blocks.xml of our theme.

Now the problem is, that executing commands grunt clean:THEME, grunt exec:THEME, grunt less:THEME and grunt watch will not create symlinked files within pub/static folder. Instead it copies the source stylesheets to the pub folder, and therefore grunt watch will not detect any changes. Of course I researched and checked solutions like cleaning cache, rebuilding anything and deploying static content before running the grunt tasks. (e.g. Magento 2 grunt exec does not actually create symlinks or What are the Magento 2 Grunt commands? From deployment?)

I also verified that there are no external imports within my custom style.less file. (https://github.com/magento/magento2/issues/1619#issuecomment-377472378) We're running under FreeBSD.

Sadly the Symlink is not created and therefore grunt does not detect changes of my custom 'style.less' file: symlink not created

Do you have any idea why this happens, or did someone experience the same with m2? Thanks in advance for all your help!

UPDATE 09.04.19:

  • u can also enable symlink form backend configuration.
    – sudo55
    Commented Apr 5, 2019 at 7:02
  • Thanks for your answer! Do you mean the option "allow symlinks" under "shops" -> "configuration" -> "developer"? This option was already enabled.
    – TurnJoke
    Commented Apr 5, 2019 at 7:22
  • okay, then you need to enable Developer mode.
    – sudo55
    Commented Apr 5, 2019 at 7:26
  • developer mode is also already enabled :) some symlinks are generated, just the ones for my custom theme not.
    – TurnJoke
    Commented Apr 5, 2019 at 7:27

3 Answers 3


Please open the file:


module.exports = {
    company_base: {
        area: 'frontend',
        name: 'Company/Base',  // <--- name must match the folder structure of your theme
        locale: 'de_DE',
        files: [
        dsl: 'less'

And check if the name matches your Theme folder (case sensitive!)

I faced the same problem as you, because my theme folder is:


but the name in the configuration was set to company/base instead of Company/Base

Then execute:

grunt refresh && grunt exec:your_theme && grunt less:your_theme && php bin/magento cache:flush full_page && grunt watch

Note: Replace your_theme with company_base in this example.

If it still does not work then you probably try to add css to _extend.less directly. This does not seem to work, you are only allowed to use this file for imports.

  • 1
    grunt refresh extremely helpful after 1000000 less changes
    – Goldy
    Commented Jul 9, 2020 at 12:30
  • 2
    @Goldy It may work for you, try grunt refresh && grunt watch. As noted in some hard-to-find Magento wisdom here: integer-net.com/magento-2-frontend-workflow-step-by-step, the exec-> less/ refresh stage has to be run before you can run watch. I should probably know why, but it works shrugs Commented Nov 29, 2020 at 23:20

Go to the dev\tools\grunt\configs\themes.js file:

Configure there your theme js just below luma:

themename: {
    area: 'frontend',
    name: 'yourvendor/themename',
    locale: 'en_US',
    files: [
    dsl: 'less'

Then run below commands serially:

php bin/magento setup:upgrade

grunt exec:themename

php bin/magento setup:static-content:deploy -f

php bin/magento cache:clean

Now run command:

grunt watch

  • Hi Chandra! Thanks for your answer. Sadly it does not work, the Symlink's still not created and grunt does not detect changes when I update my custom 'style.less' file. (see i.sstatic.net/vd11Q.png)
    – TurnJoke
    Commented Apr 5, 2019 at 9:24
  • If you want your custom less file, I suggest you other way: Go to app\design\frontend\yourvendor\themename\web\css\source: Add your _custom.less file. Override _sources.less file in app\design\frontend\yourvendor\themename\web\css\source and add below line: @import '_custom.less'; Commented Apr 5, 2019 at 9:35
  • Thanks for your reply. Do I have to add the _custom.less to themes.js or to default_head_blocks of my custom theme? Sadly grunt watch is still not working, and the website is not loading my _custom.less at all.
    – TurnJoke
    Commented Apr 9, 2019 at 8:52
  • Hey Chandra! See my updated question for details.
    – TurnJoke
    Commented Apr 9, 2019 at 9:30
  • No need to add in theme.js file or anywhere. Go to vendor\magento\theme-frontend-blank\web\css\source and copy _sources.less file. put this file in to you theme directory app\design\frontend\yourvendor\themename\web\css\source and add below line: @import '_custom.less'; Commented Apr 11, 2019 at 8:24

The answer from Black is relevant, but I found out through [this article][1] that the order of grunt tasks is important.

Make sure you run it in this order:

grunt refresh; #this is a serial command of clean-> exec -> less
#now grunt should know what files to monitor, so use watch
grunt watch;

N.B: The above article advises you to run grunt refresh (or grunt clean; grunt exec; grunt less, whatever allows you manual compilation) after changing your theme fs structure (deleting/adding files etc.) [1]: https://www.integer-net.com/magento-2-frontend-workflow-step-by-step/

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.