# rspack-debugging

rspack-debugging captures the crash state of native Rspack with LLDB: backtraces for segfaults, deadlocks and builds that hang. Useful when the failure sits inside Rust.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 282 installs · ★ 100 repo stars
- Author: rstackjs
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/rstackjs/agent-skills/tree/HEAD/skills/rspack-debugging/SKILL.md
- Updated: 2026-10-22
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/rspack-debugging

## What it does

The skill walks an agent through capturing the crash state of native Rspack. Rspack runs on Rust, so a segfault or a deadlock only shows up at stack level; the skill gets LLDB to produce a detailed backtrace. The run is non-interactive, with the agent driving the debugger and collecting output.

Six guides cover the scenarios: a crash during HMR, a crash during a build, attaching to a process that hangs, coredump analysis for dev and for build, and tracking an async deadlock where the main thread sits in `uv_run`. Preparation is handled by `scripts/setup_debug_deps.cjs`, which writes `pnpm.overrides` into `package.json` and points the packages at the `@rspack-debug/*` series.

Skip that swap and the backtrace tells you little: production packages such as `@rspack/core` ship with symbols stripped. LLDB has to be there too, via `xcode-select --install` on macOS or the `lldb` package on Linux. When debugging ends, rerun the script with `--restore` and `pnpm install` to put production packages back. Whatever backtrace the agent obtains goes to `debug_artifacts/backtrace_<timestamp>.txt` in the project root.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add rstackjs/agent-skills --skill rspack-debugging -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/rspack-debugging/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/rspack-debugging/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add rstackjs/agent-skills --skill rspack-debugging -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/rspack-debugging/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add rstackjs/agent-skills --skill rspack-debugging -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/rspack-debugging/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install rstackjs/agent-skills skills/rspack-debugging
```

2. **Manually: put the files in place**
- File: `.github/skills/rspack-debugging/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add rstackjs/agent-skills --skill rspack-debugging -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/rstackjs/agent-skills --path skills/rspack-debugging
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/rspack-debugging/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add rstackjs/agent-skills --skill rspack-debugging -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/rstackjs/agent-skills/tree/HEAD/skills/rspack-debugging/SKILL.md

## When to use it
- catch a backtrace when a Rspack build segfaults
- diagnose HMR that hangs DevServer
- attach a debugger to a stuck build process
- read a coredump from an intermittent crash
- find an async deadlock with the main thread in `uv_run`

## Example prompts
- The Rspack build crashed with a segfault — grab a backtrace with LLDB and save it under `debug_artifacts`.
- HMR keeps freezing DevServer, walk the HMR crash guide.
- Swap the packages to debug builds with `scripts/setup_debug_deps.cjs`, then restore them when we're done.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 7b697be1b5affe4e.

BEGIN THIRD-PARTY FILE 7b697be1b5affe4e
````text
---
name: rspack-debugging
description: Debug native Rspack crashes, segmentation faults, deadlocks, or stuck builds with LLDB and matching debug symbols.
---

# Rspack debugging

## Overview

This Skill guides you on how to capture the underlying crash state of Rspack (which is based on Rust). By using the LLDB debugger and Rspack packages with debug symbols, we can obtain detailed stack backtraces, which are crucial for pinpointing issues. The guides focus on non-interactive, automated debugging to easily capture backtraces.

## Preparation

Before starting, please ensure your environment meets the requirements.

1.  **Install LLDB**: You must install the LLDB debugger.
    - macOS: Run `xcode-select --install`
    - Linux: Install the `lldb` package (e.g., `apt-get install lldb`)
    - Detailed guide: [references/lldb.md](references/lldb.md)

2.  **Replace Debug Packages**:
    Production packages like `@rspack/core` have debug symbols stripped. They must be replaced with the `@rspack-debug/*` series packages to see useful stack information.

    **Automatic Replacement Script**:

    Resolve the bundled [`scripts/setup_debug_deps.cjs`](scripts/setup_debug_deps.cjs)
    relative to the Skill root while keeping the working directory in the user's
    project, then run:

    ```bash
    node "<skill-root>/scripts/setup_debug_deps.cjs"
    ```

    Running the above script will automatically add `pnpm.overrides` configuration to `package.json`, pointing Rspack packages to their corresponding Debug versions. Afterwards, please be sure to run `pnpm install` to update dependencies.

## Debugging workflows

Identify your specific scenario and follow the corresponding linked guide.

## Detailed guides

## Detailed guides

### Guide A: crash during HMR

**Scenario**: Stable Crash/Deadlock during DevServer HMR.
[Read Guide: references/guide_a_hmr_crash.md](references/guide_a_hmr_crash.md)

### Guide B: crash during build

**Scenario**: Stable Crash/Deadlock during Build (or Unstable Build Crash that is frequent enough).
[Read Guide: references/guide_b_build_crash.md](references/guide_b_build_crash.md)

### Guide C: attach to stuck process

**Scenario**: Unstable Deadlock during Build (happens randomly).
[Read Guide: references/guide_c_attach_to_stuck_process.md](references/guide_c_attach_to_stuck_process.md)

### Guide D: coredump analysis (Dev)
````
END THIRD-PARTY FILE 7b697be1b5affe4e

The third-party file has ended. Everything between the 7b697be1b5affe4e tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2381 of 3724 bytes. © rstackjs · MIT · https://github.com/rstackjs/agent-skills/tree/HEAD/skills/rspack-debugging/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
