Add troubleshooting guide

public/static/docs/sidebar.json

@@ -156,6 +156,10 @@
         "label": "Running DVC on Windows",
         "slug": "running-dvc-on-windows"
       },
+      {
+        "label": "Troubleshooting guide",
+        "slug": "troubleshooting"
+      },
       {
         "label": "Anonymized Usage Analytics",
         "slug": "analytics"

public/static/docs/user-guide/troubleshooting.md

@@ -0,0 +1,17 @@
+# Troubleshooting
+
+In this section we provide help for some of the problems that DVC user might
+stumble upon.
+
+<h2 id="many-files">Too many open files error</h2>
+
+A known problem some users run into with the `dvc pull`, `dvc fetch` and
+`dvc push` commands is `[Errno 24] Too many open files` (most common for S3
+remotes on MacOS). The more `--jobs` specified, the more file descriptors need
+to be open on the host file system for each download thread, and the limit may
+be reached, causing this error.
+
+To solve this, it's often possible to increase the open file descriptors limit,
+with `ulimit` on UNIX-like system (for example `ulimit -n 1024`), or
+[increasing Handles limit](https://blogs.technet.microsoft.com/markrussinovich/2009/09/29/pushing-the-limits-of-windows-handles/)
+on Windows. Otherwise, please try using a lower `JOBS` value.

server.js

@@ -45,6 +45,13 @@ app.prepare().then(() => {
             : pathname)
       })
       res.end()
+    } else if (req.headers.host === 'error.dvc.org') {
+      // error.dvc.org/{hdr} -> dvc.org/doc/user-guide/troubleshooting#{hdr},
+      res.writeHead(301, {
+        'Cache-Control': 'no-cache',
+        Location: `https://dvc.org/doc/user-guide/troubleshooting#${pathname}`
+      })
+      res.end()
     } else if (/^(code|data|remote)\.dvc\.org$/.test(req.headers.host)) {
       // {code/data/remote}.dvc.org -> corresponding S3 bucket
       res.writeHead(301, {