# Rspack Debugging

> Helps Rspack users and developers debug crashes or deadlocks/hangs in the Rspack build process using LLDB. Use this Skill when users encounter "Segmentation fault" errors during Rspack builds or when the build progress gets stuck.

- **Type:** Skill
- **Install:** `agentstack add skill-rstackjs-agent-skills-rspack-debugging`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [rstackjs](https://agentstack.voostack.com/s/rstackjs)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [rstackjs](https://github.com/rstackjs)
- **Source:** https://github.com/rstackjs/agent-skills/tree/main/skills/rspack-debugging

## Install

```sh
agentstack add skill-rstackjs-agent-skills-rspack-debugging
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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**:

    ```bash
    node ${CLAUDE_PLUGIN_ROOT}/skills/debugging/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)

**Scenario**: Unstable Crash during DevServer HMR (hard to catch interactively).
[Read Guide: references/guide_d_coredump_analysis_dev.md](references/guide_d_coredump_analysis_dev.md)

### Guide E: Coredump Analysis (Build)

**Scenario**: Unstable Crash during Build.
[Read Guide: references/guide_e_coredump_analysis_build.md](references/guide_e_coredump_analysis_build.md)

### Guide F: Async Deadlock Identification

**Scenario**: Unstable Async Deadlock. Main thread stuck in `uv_run`.
[Read Guide: references/guide_f_async_deadlock.md](references/guide_f_async_deadlock.md)

## Saving Debug Artifacts

**Critical Instruction for Agents**:
When you successfully obtain a backtrace or a tracing log, you **MUST** save it to a local file in the user's project directory so it is preserved after the session.

1.  **Create Directory**: Ensure a directory named `debug_artifacts` exists in the project root.
2.  **Save Backtraces**: Write the full output of `thread backtrace all` to `debug_artifacts/backtrace_.txt`.
3.  **Save Tracing Logs**: (Only if using Tracing Skill)

## Environment Restoration

After debugging is complete, restore your `package.json` to use production packages:

```bash
node ${CLAUDE_PLUGIN_ROOT}/skills/debugging/scripts/setup_debug_deps.cjs --restore
pnpm install
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [rstackjs](https://github.com/rstackjs)
- **Source:** [rstackjs/agent-skills](https://github.com/rstackjs/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-rstackjs-agent-skills-rspack-debugging
- Seller: https://agentstack.voostack.com/s/rstackjs
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.