What causes "LLVM does not have support for catchpad" in rust-lang/rust?

Install/use the rustc toolchain with its bundled LLVM.

LLVM does not have support for catchpad

Error message

LLVM does not have support for catchpad

What it means

This panic is emitted by `Builder::catch_pad` (builder.rs:1326-1336) when the LLVM-C call `LLVMBuildCatchPad` returns null, meaning the linked LLVM cannot emit a `catchpad` instruction. catchpad is part of Windows SEH funclet-based EH used to model `catch` blocks on MSVC targets; a null return indicates the LLVM backend lacks funclet EH. The `.expect(...)` guard turns the missing LLVM feature into a hard compiler abort.

Source

Thrown at compiler/rustc_codegen_llvm/src/builder.rs:1336

    fn cleanup_ret(&mut self, funclet: &Funclet<'ll>, unwind: Option<&'ll BasicBlock>) {
        unsafe {
            llvm::LLVMBuildCleanupRet(self.llbuilder, funclet.cleanuppad(), unwind)
                .expect("LLVM does not have support for cleanupret");
        }
    }

    fn catch_pad(&mut self, parent: &'ll Value, args: &[&'ll Value]) -> Funclet<'ll> {
        let ret = unsafe {
            llvm::LLVMBuildCatchPad(
                self.llbuilder,
                parent,
                args.as_ptr(),
                args.len() as c_uint,
                c"catchpad".as_ptr(),
            )
        };
        Funclet::new(ret.expect("LLVM does not have support for catchpad"))
    }

    fn catch_switch(
        &mut self,
        parent: Option<&'ll Value>,
        unwind: Option<&'ll BasicBlock>,
        handlers: &[&'ll BasicBlock],
    ) -> &'ll Value {
        let ret = unsafe {
            llvm::LLVMBuildCatchSwitch(
                self.llbuilder,
                parent,
                unwind,
                handlers.len() as c_uint,
                c"catchswitch".as_ptr(),
            )
        };
        let ret = ret.expect("LLVM does not have support for catchswitch");

View on GitHub (pinned to 22057b88b0)

Solutions

Install/use the rustc toolchain with its bundled LLVM.
Rebuild LLVM with EH and the X86 (MSVC) target enabled.
Pin rustc to a release known to ship a matching LLVM.
Avoid the MSVC target (use `*-pc-windows-gnu` or a non-Windows target) if you cannot fix LLVM.

Example fix

// before
rustc --target x86_64-pc-windows-msvc --sysroot=/opt/custom-llvm-sysroot
// after
rustc +stable --target x86_64-pc-windows-msvc   # toolchain's bundled LLVM

Defensive patterns

Strategy: validation

Validate before calling

# catchpad only matters when catching C++/SEH exceptions via extern "C"/
# extern "C-unwind". Gate such crates behind a target check.
case "${RUST_TARGET:-$(rustc -vV | awk '/host:/ {print $2}')}" in
  *windows-msvc*|*windows-gnu*) rustup show active-toolchain >/dev/null 2>&1 \
      || echo 'custom toolchain: confirm LLVM has WinEH before building catch handlers' ;;
  *) ;;
esac

Try / catch

out="$(cargo build 2>&1)"; rc=$?
if [ $rc -ne 0 ]; then
  case "$out" in
    *"LLVM does not have support for catchpad"*)
      echo "LLVM lacks SEH catchpad lowering; rebuild with a WinEH-enabled LLVM" >&2 ;;
    *) echo "$out" >&2 ;;
  esac
  exit $rc
fi

Prevention

When crossing the FFI boundary with C++ exceptions, target *-windows-msvc and a stock rustup LLVM.
Do not enable -Cpanic=unwind for SEH-catching code on a hand-built LLVM with WinEH disabled.
Reproduce the failure on the official toolchain first; if it disappears, the cause is the custom LLVM, not your code.
Track the rustc/LLVM version that introduced the personality you depend on, and pin it.

When it happens

Trigger: Lowering a Rust `catch`/try block (or any SEH catch construct) when targeting `*-pc-windows-msvc`, while the LLVM library that rustc was linked against does not implement the catchpad intrinsic. Fires inside `LLVMBuildCatchPad(...).expect(...)` once LLVM returns None.

Common situations: Custom rustc builds against a stripped-down LLVM; distro LLVM packages built without exception handling; mismatched `rustc_codegen_llvm` crate and LLVM version; cross-compiling to MSVC with a Linux-built LLVM lacking the X86 MSVC EH path.

Related errors

AI-assisted analysis of rust-lang/rust@22057b88b0 (2026-08-03). Data as JSON: /data/errors/858f9202ddafb677.json. Report an issue: GitHub.