Resolve #1607: explain common ESM errors in troubleshooting page

website/docs/troubleshooting.md

@@ -85,3 +85,27 @@ const a = foo?.bar;
 ```
 
 When you try to run this code, node 12 will throw a `SyntaxError`.  To fix this, you must switch to `"target": "es2019"` or lower so TypeScript transforms `?.` into something `node` can understand.
+
+### `ERR_REQUIRE_ESM`
+
+This error is thrown by node when a module is `require()`d, but node believes it should execute as native ESM.  This can happen for a few reasons:
+
+- You have installed an ESM dependency but your own code compiles to CommonJS.
+  - Solution: configure your project to compile and execute as native ESM. [Docs](./imports.md#native-ecmascript-modules)
+  - Solution: downgrade the dependency to an older, CommonJS version.
+- You have moved your project to ESM but still have a config file, such as `webpack.config.js`, which must be executed as CommonJS
+  - Solution: if supported by the relevant tool, rename your config file to `.cjs`
+  - Solution: Configure a module type override. [Docs](./module-type-overrides.md)
+- You have a mix of CommonJS and native ESM in your project
+  - Solution: double-check all package.json "type" and tsconfig.json "module" configuration [Docs](./imports.md)
+  - Solution: consider simplifying and switch to all CommonJS or all native ESM
+
+### `ERR_UNKNOWN_FILE_EXTENSION`
+
+This error is thrown by node when a module has an unrecognized file extension, or no extension at all, and is being executed as native ESM.  This can happen for a few reasons:
+
+- You are using a tool which has an extensionless binary, such as `mocha`.
+  - CommonJS supports extensionless files but native ESM does not.
+  - Solution: upgrade to ts-node >=[v10.6.0](https://github.com/TypeStrong/ts-node/releases/tag/v10.6.0), which implements a workaround.
+- Our ESM loader is not installed.
+  - Solution: Use `ts-node-esm`, `ts-node --esm`, or add `"ts-node": {"esm": true}` to your tsconfig.json.  [Docs](./imports.md#native-ecmascript-modules)