Proposal: pybind11-debug — a gdb wrapper that diagnoses "Caught an unknown exception!" and native crashes direct from python console

[GabrielJMS]

The problem

When a C++ exception escapes a bound function and matches none of the registered
translators, pybind11's final catch (...) fallback (in detail/internals.h) raises:

RuntimeError: Caught an unknown exception!

At that point every diagnostic is gone, the type, the message, and the C++ stack
have all been destroyed by unwinding. The most common real-world cause is an
exception type that doesn't derive from std::exception, which is routine when
binding large third-party C++ SDKs that ship their own exception hierarchies.
Users googling that message today find no actionable guidance in the docs.

The sibling failure mode, a segfault inside the extension, is even worse: the
interpreter dies with no traceback at all.

Both are diagnosable at the origin with gdb, but the incantations (breaking on
__cxa_throw, filtering out the thousands of benign import-time throws a CPython
process generates, reading the std::type_info out of the Itanium-ABI registers)
are beyond what we can reasonably ask a typical extension user to reinvent.

Proposal

A single pure-stdlib module, pybind11/debug.py, exposed as pybind11-debug (and
python -m pybind11.debug), following the existing pybind11-config CLI precedent:

$ pybind11-debug my_script.py args...

It runs the script under gdb -batch with an injected gdb-Python script that:

• Traps C++ throws at __cxa_throw, before unwinding, and reports only throws
  whose stack passes through an extension module (auto-detected via
  importlib.machinery.EXTENSION_SUFFIXES; --target narrows the filter). It
  prints the demangled exception type, a heuristically recovered message, and a
  backtrace annotated with which frames belong to the extension — with file:line
  when the extension was built with -g, function names otherwise. Throws in
  namespace pybind11 (error_already_set etc.) are recognized and suppressed by
  default, since pybind11 translates those correctly itself.
• Traps fatal signals (SIGSEGV/SIGABRT/SIGBUS/SIGFPE), prints the native
  backtrace at the faulting frame, then forwards the signal so faulthandler can
  print the Python-side stack too (which script line triggered the crash).
• Uses exit codes 1 (something reported) / 0 (clean) / 2 (usage or platform
  error), so it can be scripted in CI.

Before / after

Before — everything the user sees today:

Traceback (most recent call last):
  File "process.py", line 4, in <module>
    result = mymodule.process_file(path)
RuntimeError: Caught an unknown exception!

After — transcript from a production extension binding a large C++ SDK (names
anonymized):

  === C++ THROW in _mymodule ===
  type: DummyException1
  msg (heuristic): 'dummy error message recovered from the exception object'
  backtrace (* = extension module):
   #0   __cxa_throw  [libstdc++.so.6]
  *#2   DummyClass1::DummyClass1(...)  [_mymodule.cpython-312-x86_64-linux-gnu.so]
  *#6   DummyClass2::dummyMethod1(...)  [_mymodule.cpython-312-x86_64-linux-gnu.so]
  *#17  dummy_function1(...)  (src/dummy_file1.cpp:198)  [_mymodule.cpython-312-x86_64-linux-gnu.so]
  *#29  operator()  (src/bindings.cpp:94)  [_mymodule.cpython-312-x86_64-linux-gnu.so]
  *#34  pybind11::cpp_function::dispatcher  (.../pybind11.h:971)  [...]

That took the bug from "unknown exception, somewhere" to an exact call site, and a
one-clause fix (catching the SDK's exception base class, which does not derive from
std::exception.

Scope and cost

• Platforms: Linux, x86-64 + aarch64 (the throw-argument register conventions
  are a two-entry table, designed for extension). Clean exit 2 with guidance
  elsewhere: MSVC users get pointed at the VS debugger's "break on C++ exceptions";
  an lldb backend for macOS is plausible future work.
• Dependencies: none — stdlib only. gdb is checked at runtime with an
  actionable error message. Zero import cost for the package (nothing imports the
  module implicitly).
• Tests: no new C++ needed — test_exceptions already has throws3(), which
  throws MyException3, the canonical non-std::exception type the test suite
  asserts produces "Caught an unknown exception!". Tests self-skip without
  gdb/Linux, with a canary fixture for containerized runners where ptrace is
  restricted. CI cost: adding gdb to one apt-get line in one Linux job.
• Docs: a new docs/advanced/debugging.md page, cross-linked from the FAQ
  crash entry and the deadlock page's debugging tips.

Open questions

1. Naming: pybind11-debug / python -m pybind11.debug, or something
   narrower like pybind11-diagnose? Everything is behind one main(), so a
   rename is mechanical.
2. Fatal-signal test: the PR would include a guarded test that deliberately
   segfaults a child process via ctypes.string_at(0). Comfortable with that in
   CI, or should the initial PR keep only the throw-path test?
3. Shipping vs. linking: if you'd rather not ship a debugging tool in the
   wheel, would you take the docs page plus a link to it as a standalone package?
   (I'd argue shipping is better: the tool encodes assumptions about pybind11's
   namespace mangling that should stay versioned with the library itself.)

I have a working implementation and can open a PR (tool + tests + docs, ~600 lines total) if
there's interest.