A panic on PG16, and the fix that needed fixing
A multi-row insert panicked inside ParadeDB when an index expression re-entered the executor. My first fix traded that panic for a different one. The merged fix gives every nesting level its own frame.
paradedb #4924 merged 17 May 2026 +244 −46 in 4 files issue #4843
The report
A user updating a table of about three million rows got this from a bm25 index that includes an expression,
bingo.cansmiles("smiles"):
Why it happened
Postgres 17 added aminsertcleanup, which lets an index defer work until an insert has finished. On
PG15 and PG16, ParadeDB approximates it by hooking ExecutorRun, ExecutorFinish and
ProcessUtility, and keeping a stack of insert states that are still in progress.
The run hook pushed a new empty entry for every ExecutorRun. When the index expression started a
run of its own partway through the insert, that nested run put an empty entry on top of the one holding the
insert's state.
EXECUTOR_RUN_STACK, top first
None pushed by the nested ExecutorRun Some { index: state } the insert in progress The next lookup reads the top, finds nothing, and hits unreachable!
First fix: count the depth
If the top entry already held state, a nested run would bump a counter and leave the stack alone, and the matching finish would decrement it. Cleanup ran only once the count was back at zero.
A test that proved nothing
The real trigger needs a third-party extension, so I tried to reproduce the nesting without it. I wrote a function that runs a query through SPI, used it in an expression index, watched the test pass, and said so on the pull request.
Then I ran the same test against the unfixed code. It passed there too. Standard SPI does not re-enter the
ExecutorRun hook, so the test had never exercised the bug. I retracted the claim and removed the
test.
The fix was validated by hand on PG16 with the extension installed, and later by the person who reported the bug.
What review found
A maintainer traced a case the counter broke: a trigger, or a function in an index expression, that inserts back into the same indexed table. The original code had handled this, because every run got its own entry. With the counter, the nested insert landed in the same map as the outer one.
EXECUTOR_RUN_STACK with the depth counter
Some { index: outer state }, depth: 1 one entry, shared by both inserts The nested insert asks for a slot for the same index, finds it occupied, and hits a different unreachable!
I walked the trace on paper and it held. The counter had traded one panic for another on a narrower path.
The rebuild: one frame per invocation
The merged fix removes the counter. Each hook invocation creates a FrameGuard, which pushes a fresh
frame when it is created and cleans that frame up when it is dropped. A nested insert gets an empty frame of its
own, so it cannot collide with the outer one, and cleanup happens on every exit path because it is tied to
scope.
EXECUTOR_RUN_STACK with FrameGuard
InsertFrame { index: inner state } owned by the nested invocation's guard InsertFrame { index: outer state } owned by the outer invocation's guard Each guard cleans up and pops its own frame as it goes out of scope, innermost first.
impl Drop for FrameGuard {
fn drop(&mut self) {
// Safety: we are on the Postgres main thread, inside an executor hook whose entry pushed
// one frame, so the stack is non-empty.
unsafe {
if std::thread::panicking() {
// We are already unwinding. Calling insertcleanup now risks a second panic,
// which would abort the process. Leave the frame in place; the xact-abort
// callback registered above will clear the stack when the transaction rolls back.
return;
}
let frame = EXECUTOR_RUN_STACK
.pop()
.expect("FrameGuard::drop: stack underflow — frame was never pushed");
for (_, mut entry) in frame.active {
// …
let mode = std::mem::replace(&mut entry.insert_state.mode, InsertMode::Completed);
insertcleanup(&entry.insert_state, mode);
}
}
}
}The guard does one more thing. If it is dropped while the thread is already unwinding from a panic, it skips cleanup, because a second panic at that point would abort the process.
Writing down what holds
The module now states its invariants, including the one it does not provide.
//! # Stack invariants
//!
//! * `EXECUTOR_RUN_STACK.len()` equals the number of live [`FrameGuard`] instances. Each guard
//! pushes exactly one frame on creation and pops exactly one frame on drop.
//!
//! * `push_insert_state` always targets the **top** frame. `aminsert` is always called from
//! within the hook invocation that created its frame, so the top of the stack is always the
//! correct frame.
// …
//! * **What is NOT guaranteed**: the stack is not "all non-empty below all empty". A
//! `ProcessUtility` hook can push a frame on top of an active `ExecutorRun` frame. This is
//! fine — each frame is independent and cleaned up by its own guard.One more path
Before merge, review raised INSERT ... RETURNING read through a cursor: several runs against a
single finish. Cleaning up at the end of each run could leave a cached pointer to state that was already gone,
so the guard now clears that cache as part of cleanup.
Confirmed
The person who reported the bug ran the patch against their own setup and confirmed the panic was gone. It merged on 17 May 2026, twelve commits after the first version.
The full pull request on GitHub Next: Wrong rows from a self-join