docs: common errors

apps/docs/src/.vitepress/config.ts

@@ -32,6 +32,7 @@ export default defineConfig({
           { text: 'CLI', link: '/guide/cli' },
           { text: 'Node.js API', link: '/guide/api' },
           { text: 'Website', link: '/guide/web' },
+          { text: 'Common Errors', link: '/guide/common-errors' },
         ],
       },
       {

apps/docs/src/guide/common-errors.md

@@ -0,0 +1,36 @@
+# Common Errors
+
+## isolated-vm
+
+If you see errors like
+
+> - isolated_vm.node: undefined symbol: \_ZNK2v815ValueSerializer8Delegate20SupportsSharedValuesEv
+> - ERR_DLOPEN_FAILED
+> - Segmentation fault
+
+it means that the [isolated-vm](https://github.com/laverdet/isolated-vm) package was built against a different version of Node.js than the one you are using. This can happen if you upgrade Node.js after installing `webcrack`.
+
+To fix this, run `npm rebuild isolated-vm` in your project directory or delete the `node_modules/isolated-vm` directory and run `npm install` again.
+
+## Heap Out Of Memory
+
+> FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory
+
+Fix by running node with the [--max-old-space-size](https://nodejs.org/api/cli.html#--max-old-space-sizesize-in-megabytes) flag. For example:
+
+```sh
+NODE_OPTIONS="--max-old-space-size=8192" webcrack bundle.js
+```
+
+or
+
+```sh
+node --max-old-space-size=8192 your-script.js
+```
+
+## `__DECODE_0__`
+
+If this appears in your code, the deobfuscator failed to decode a string from the string array.
+This can happen in forked javascript-obfuscator versions or when `Dead Code Injection` is enabled.
+
+[Open an issue](https://github.com/j4k0xb/webcrack/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml) if you encounter this.

packages/webcrack/src/deobfuscate/vm.ts

@@ -73,6 +73,16 @@ export class VMDecoder {
       return result as unknown[];
     } catch (error) {
       debug('webcrack:deobfuscate')('vm code:', code);
+      if (
+        error instanceof Error &&
+        (error.message.includes('undefined symbol') ||
+          error.message.includes('Segmentation fault'))
+      ) {
+        throw new Error(
+          'isolated-vm version mismatch. Check https://webcrack.netlify.app/docs/guide/common-errors.html#isolated-vm',
+          { cause: error },
+        );
+      }
       throw error;
     }
   }