> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Debugging

## Debugging with VS Code

1. Install `go install github.com/go-delve/delve/cmd/dlv@latest`
2. Install VS Code extension [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer) and [CodeLLDB](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb)
3. build `@rspack/cli` and napi binding by run `pnpm install && pnpm -w build:cli:dev`
4. In VS Code's `Run and Debug` tab, select `Debug Rspack` to start debugging the initial launch of `@rspack/cli` with a simple rspack project. This task can be configured in `.vscode/launch.json`.

## Using `@rspack-debug/core`

Frameworks and tools that integrate Rspack usually depend on the release build of `@rspack/core`. The release package is suitable for normal builds, but it does not include some debug-only capabilities. When you need these capabilities for local investigation, override `@rspack/core` with `@rspack-debug/core` in the project that runs the build.

For example, with pnpm:

```json title="package.json"
{
  "pnpm": {
    "overrides": {
      "@rspack/core": "npm:@rspack-debug/core@latest"
    },
    "peerDependencyRules": {
      "allowAny": ["@rspack/*"]
    }
  }
}
```

Then reinstall dependencies and run the original build command again. For example, if the project builds through Rsbuild:

```bash
pnpm install
RSPACK_PROFILE=OVERVIEW RSPACK_TRACE_LAYER=perfetto rsbuild build
```

`@rspack-debug/core` should only be used for local debugging and diagnostics. Prefer pinning it to the same version as the original `@rspack/core` dependency when investigating a version-specific issue, and remove the override after the investigation.

### Common debugging scenarios guide

#### Debugging Rust

Simply set breakpoints in the specified Rust code and start `Debug Rspack` to begin debugging.

#### Debugging JavaScript

When starting `Debug Rspack`, select the `--inspect` or `--inspect-brk` option, then start `Attach JavaScript` and choose the PID of the corresponding process.

#### Debugging a running Rspack process

When Rspack is integrated into other frameworks or tools (such as Nx), it may be difficult to independently start Rspack in Launch mode. In this case, you can debug the code through attach mode. Start `Attach Rust` and select the PID of the Rspack process, and start `Attach JavaScript` to debug JavaScript.

#### Debugging a Rspack process with a deadlock

When using `Attach Rust` to attach the debugger to the Rspack process, click the Pause button on the Debugger to set breakpoints at the deadlock scene.

## rust-lldb

`rust-lldb` can be used to get panic information from debug builds

```bash
rust-lldb -- node /path/to/rspack build
```

Once it launches, press `r` for running the program.

For example, `examples/arco-pro` crashes without any information before [this fix](https://github.com/web-infra-dev/rspack/pull/3195/files):

```
rspack/examples/arco-pro ❯ node ../../packages/rspack-cli/bin/rspack build
Rspack ██████████████████████░░░░░░░░░░░░░░░░░░ 56% building ./pages/welcome
zsh: bus error  node ../../packages/rspack-cli/bin/rspack build
```

Using `rust-lldb`

```bash
rspack/examples/arco-pro ❯ rust-lldb -- node ../../packages/rspack-cli/bin/rspack build
```

Press `r` and it prints:

```
Process 23110 stopped
* thread #10, name = 'tokio-runtime-worker', stop reason = EXC_BAD_ACCESS (code=2, address=0x70000cc66560)
    frame #0: 0x0000000140d0db4b rspack.darwin-x64.node`swc_ecma_parser::parser::expr::ops::_$LT$impl$u20$swc_ecma_parser..parser..Parser$LT$I$GT$$GT$::parse_unary_expr::h29f49330a806839c(self=0x0000000000000000) at ops.rs:244
   241 	    /// Parse unary expression and update expression.
   242 	    ///
   243 	    /// spec: 'UnaryExpression'
-> 244 	    pub(in crate::parser) fn parse_unary_expr(&mut self) -> PResult<Box<Expr>> {
   245 	        trace_cur!(self, parse_unary_expr);
   246 	        let start = cur_pos!(self);
   247
Target 0: (node) stopped.
```