Troubleshooting and known issues

Troubleshooting

Missing theme npm dependencies

For any Docsy install mode, if the theme’s npm packages aren’t available, Hugo fails while compiling SCSS with an error like:

TOCSS: failed to transform "/scss/main.scss" (text/x-scss):
File to import not found or unreadable: ../../vendor/bootstrap/scss/functions.

To fix this, install the theme’s npm dependencies for your setup, then rebuild:

• Example-site-based projects: run npm run install:safe from your site root; in an older copy without that script, use your repository’s own install script.
• Sites using Docsy as an NPM package: install from your site root, for example with npm install.
• Hugo module sites built from scratch: see Install npm dependencies.
• Sites using Docsy as a Git submodule or a cloned theme: run npm run install:theme-deps from themes/docsy.

Missing Dart Sass compiler

If Hugo can’t find the Dart Sass sass CLI on its PATH, it fails while compiling SCSS with an error like:

TOCSS-DART: failed to transform "scss/main.scss" (text/x-scss).

To fix this, follow Install Dart Sass, then rebuild.

Known issues

The following issues are known on MacOS and on Windows Subsystem for Linux:

MacOS

Errors: too many open files or fatal error: pipe failed

By default, MacOS permits a small number of open File Descriptors. For larger sites, or when you’re simultaneously running multiple applications, you might receive one of the following errors when you run hugo server to preview your site locally:

• POSTCSS v7 and earlier:

  ERROR 2020/04/14 12:37:16 Error: listen tcp 127.0.0.1:1313: socket: too many open files
  

• POSTCSS v8 and later:

  fatal error: pipe failed
  

Workaround

To temporarily allow more open files:

1. View your current settings by running:

   sudo launchctl limit maxfiles
   

2. Increase the limit to 65535 files by running the following commands. If your site has fewer files, you can choose to set lower soft (65535) and hard (200000) limits.

   sudo launchctl limit maxfiles 65535 200000
   ulimit -n 65535
   sudo sysctl -w kern.maxfiles=200000
   sudo sysctl -w kern.maxfilesperproc=65535
   

Note that you might need to set these limits for each new shell. Learn more about these limits and how to make them permanent.

Windows Subsystem for Linux (WSL)

If you’re using WSL, ensure that you’re running hugo on a Linux mount of the filesystem, rather than a Windows one, otherwise you may get unexpected errors.