diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 2f378826fa3cb4..e61c9cc00d6262 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -211,6 +211,10 @@ export default defineConfig({
               text: 'Comparisons',
               link: '/guide/comparisons'
             },
+            {
+              text: 'Troubleshooting',
+              link: '/guide/troubleshooting'
+            },
             {
               text: 'Migration from v2',
               link: '/guide/migration'
diff --git a/docs/config/server-options.md b/docs/config/server-options.md
index 33208bd4b04155..29a3582665c7a6 100644
--- a/docs/config/server-options.md
+++ b/docs/config/server-options.md
@@ -145,6 +145,8 @@ Set `server.hmr.overlay` to `false` to disable the server error overlay.
 
 When `server.hmr.server` is defined, Vite will process the HMR connection requests through the provided server. If not in middleware mode, Vite will attempt to process HMR connection requests through the existing server. This can be helpful when using self-signed certificates or when you want to expose Vite over a network on a single port.
 
+Check out [`vite-setup-catalogue`](https://github.com/sapphi-red/vite-setup-catalogue) for some examples.
+
 ::: tip NOTE
 
 With the default configuration, reverse proxies in front of Vite are expected to support proxying WebSocket. If the Vite HMR client fails to connect WebSocket, the client will fallback to connecting the WebSocket directly to the Vite HMR server bypassing the reverse proxies:
diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md
new file mode 100644
index 00000000000000..c7e558f0f08192
--- /dev/null
+++ b/docs/guide/troubleshooting.md
@@ -0,0 +1,67 @@
+# Troubleshooting
+
+See [Rollup's troubleshooting guide](https://rollupjs.org/guide/en/#troubleshooting) for more information too.
+
+If the suggestions here don't work, please try posting questions on [GitHub Discussions](https://github.com/vitejs/vite/discussions) or in the `#help` channel of [Vite Land Discord](https://chat.vitejs.dev).
+
+## CLI
+
+### `Error: Cannot find module 'C:\foo\bar&baz\vite\bin\vite.js'`
+
+The path to your project folder may include `?`, which doesn't work with `npm` on Windows ([npm/cmd-shim#45](https://github.com/npm/cmd-shim/issues/45)).
+
+You will need to either:
+
+- Switch to another package manager (e.g. `pnpm`, `yarn`)
+- Remove `?` from the path to your project
+
+## Dev Server
+
+### Requests are stalled forever
+
+If you are using Linux, file descriptor limits and inotify limits may be causing the issue. As Vite does not bundle most of the files, browsers may request many files which require many file descriptors, going over the limit.
+
+To solve this:
+
+- Increase file descriptor limit by `ulimit`
+
+  ```shell
+  # Check current limit
+  $ ulimit -Sn
+  # Change limit (temporary)
+  $ ulimit -Sn 10000 # You might need to change the hard limit too
+  # Restart your browser
+  ```
+
+- Increase the following inotify related limits by `sysctl`
+
+  ```shell
+  # Check current limits
+  $ sysctl fs.inotify
+  # Change limits (temporary)
+  $ sudo sysctl fs.inotify.max_queued_events=16384
+  $ sudo sysctl fs.inotify.max_user_instances=8192
+  $ sudo sysctl fs.inotify.max_user_watches=524288
+  ```
+
+## HMR
+
+### Vite detects a file change but the HMR is not working
+
+You may be importing a file with a different case. For example, `src/foo.js` exists and `src/bar.js` contains:
+
+```js
+import './Foo.js' // should be './foo.js'
+```
+
+Related issue: [#964](https://github.com/vitejs/vite/issues/964)
+
+### Vite does not detect a file change
+
+If you are running Vite with WSL2, Vite cannot watch file changes in some conditions. See [`server.watch` option](/config/server-options.md#server-watch).
+
+### A full reload happens instead of HMR
+
+If HMR is not handled by Vite or a plugin, a full reload will happen.
+
+Also if there is a dependency loop, a full reload will happen. To solve this, try removing the loop.