Known issues

Known issues when installing Docsy theme.

The following issues are know 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 set 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.


Last modified January 10, 2023: add content from docsy userguide (6b676a8)