Wrap recipe errors with RecipeError to attribute failures to a nested recipe

The `Consumer<Throwable>` returned by `ExecutionContext#getOnError()` previously
received the raw throwable from a failing recipe, leaving downstream tooling no
way to tell which nested recipe (in a large declarative recipe with hundreds or
thousands of children) actually produced the failure.

Introduce `RecipeError` — a `RuntimeException` carrying the recipe path
(root → leaf) and source path — and wrap throwables at the single chokepoint
`RecipeRunCycle.handleError` and the run-timeout site before invoking the
`onError` consumer. The `SourcesFileErrors` data table continues to receive
the original sanitized stack trace, so attribution there is unchanged.

Update `RewriteTest`'s default consumer to unwrap the new `RecipeError`
before its `instanceof RecipeRunException` check.

Author: steve-aom-elliott

rewrite-core/src/main/java/org/openrewrite/RecipeError.java

@@ -0,0 +1,60 @@
+/*
+ * Copyright 2026 the original author or authors.
+ * <p>
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * https://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.openrewrite;
+
+import lombok.Getter;
+import org.jspecify.annotations.Nullable;
+
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * Wraps an exception thrown by a recipe so that {@link ExecutionContext#getOnError()}
+ * consumers can attribute the failure to the specific nested recipe and source file
+ * that produced it. This is especially useful for large declarative recipes (e.g.
+ * thousands of nested recipes) where the underlying stack trace alone does not
+ * reveal which recipe ran into trouble.
+ */
+@Getter
+public class RecipeError extends RuntimeException {
+
+    /**
+     * The names of the recipes from root to leaf at the time of failure.
+     * The last element is the recipe that directly threw.
+     */
+    private final List<String> recipeStack;
+
+    /**
+     * The path of the source file being processed when the error occurred,
+     * or {@code null} when the error was raised outside of a per-source context
+     * (for example, during scanning recipe generation).
+     */
+    private final @Nullable String sourcePath;
+
+    public RecipeError(List<String> recipeStack, @Nullable String sourcePath, Throwable cause) {
+        super(cause);
+        this.recipeStack = Collections.unmodifiableList(recipeStack);
+        this.sourcePath = sourcePath;
+    }
+
+    /**
+     * @return the leaf recipe name (the recipe that directly threw), or
+     * {@code "unknown"} if the recipe stack is empty.
+     */
+    public String getRecipeName() {
+        return recipeStack.isEmpty() ? "unknown" : recipeStack.get(recipeStack.size() - 1);
+    }
+}

rewrite-core/src/main/java/org/openrewrite/scheduling/RecipeRunCycle.java

@@ -151,7 +151,7 @@ public LSS scanSources(LSS sourceSet) {
                                 return source;
                             });
                         } catch (Throwable t) {
-                            after = handleError(recipe, source, after, t);
+                            after = handleError(recipeStack, source, after, t);
                             // We don't normally consider anything the scanning phase does to be a change
                             // But this simplifies error reporting so that exceptions can all be handled the same
                             assert after != null;
@@ -183,7 +183,7 @@ private void flushScanBatch(BatchState batch, SourceFile source) {
             batch.rpc.batchVisit(source, ctx, rootCursor, batch.items);
         } catch (Throwable t) {
             if (!batch.recipeStacks.isEmpty()) {
-                handleError(batch.recipeStacks.get(0).peek(), source, source, t);
+                handleError(batch.recipeStacks.get(0), source, source, t);
             }
         }
 
@@ -211,7 +211,7 @@ public LSS generateSources(LSS sourceSet) {
                                     return source;
                                 });
                             } catch (Throwable t) {
-                                handleError(recipe, source, source, t);
+                                handleError(recipeStack, source, source, t);
                             }
                         }
                     }
@@ -243,7 +243,7 @@ public LSS generateSources(LSS sourceSet) {
                             madeChangesInThisCycle.add(recipe);
                         }
                     } catch (Throwable t) {
-                        handleError(recipe, new Quark(Tree.randomId(), Paths.get("error during generation"), Markers.EMPTY, null, null), null, t);
+                        handleError(recipeStack, new Quark(Tree.randomId(), Paths.get("error during generation"), Markers.EMPTY, null, null), null, t);
                     }
                 }
                 return acc;
@@ -316,7 +316,7 @@ void clear() {
                 if (duration.compareTo(ctx.getMessage(ExecutionContext.RUN_TIMEOUT, Duration.ofMinutes(4))) > 0) {
                     if (thrownErrorOnTimeout.compareAndSet(false, true)) {
                         RecipeTimeoutException t = new RecipeTimeoutException(recipe);
-                        ctx.getOnError().accept(t);
+                        ctx.getOnError().accept(wrapForAttribution(recipeStack, src.getSourcePath().toString(), t));
                         ctx.getOnTimeout().accept(t, ctx);
                     }
                     return src;
@@ -382,7 +382,7 @@ void clear() {
                 if (isInBatch) {
                     batch.clear();
                 }
-                after = handleError(recipe, src, after, t);
+                after = handleError(recipeStack, src, after, t);
             }
             if (after != null && after != src) {
                 after = addRecipesThatMadeChanges(recipeStack, after);
@@ -417,7 +417,7 @@ void clear() {
                 if (!(t instanceof RecipeRunException)) {
                     source = Markup.error(source, t);
                 }
-                source = handleError(batch.recipeStacks.get(0).peek(), originalBefore, source, t);
+                source = handleError(batch.recipeStacks.get(0), originalBefore, source, t);
                 if (source != null && source != beforeError) {
                     source = addRecipesThatMadeChanges(batch.recipeStacks.get(0), source);
                 }
@@ -720,9 +720,9 @@ private void recordSourceFileResult(@Nullable String beforePath, @Nullable Strin
         recordSourceFileResult(beforePath, afterPath, recipeStack.subList(0, recipeStack.size() - 1), ctx);
     }
 
-    private @Nullable SourceFile handleError(Recipe recipe, SourceFile sourceFile, @Nullable SourceFile after,
+    private @Nullable SourceFile handleError(List<Recipe> recipeStack, SourceFile sourceFile, @Nullable SourceFile after,
                                              Throwable t) {
-        ctx.getOnError().accept(t);
+        ctx.getOnError().accept(wrapForAttribution(recipeStack, sourceFile.getSourcePath().toString(), t));
 
         if (t instanceof RecipeRunException && after != null) {
             try {
@@ -738,13 +738,21 @@ private void recordSourceFileResult(@Nullable String beforePath, @Nullable Strin
         // This is so the error is associated with the original source file, and its original source path.
         errorsTable.insertRow(ctx, new SourcesFileErrors.Row(
                 sourceFile.getSourcePath().toString(),
-                recipe.getName(),
+                recipeStack.get(recipeStack.size() - 1).getName(),
                 ExceptionUtils.sanitizeStackTrace(t, RecipeScheduler.class)
         ));
 
         return after;
     }
 
+    private static RecipeError wrapForAttribution(List<Recipe> recipeStack, @Nullable String sourcePath, Throwable t) {
+        List<String> recipePath = new ArrayList<>(recipeStack.size());
+        for (Recipe r : recipeStack) {
+            recipePath.add(r.getName());
+        }
+        return new RecipeError(recipePath, sourcePath, t);
+    }
+
     private static <S extends SourceFile> S addRecipesThatMadeChanges(List<Recipe> recipeStack, S afterFile) {
         return afterFile.withMarkers(afterFile.getMarkers().computeByType(
                 RecipesThatMadeChanges.create(recipeStack),

rewrite-core/src/test/java/org/openrewrite/RecipeSchedulerTest.java

@@ -83,6 +83,79 @@ void exceptionsCauseResult() {
         );
     }
 
+    @Test
+    void onErrorReceivesRecipeErrorWithLeafRecipeAndSourcePath() {
+        List<RecipeError> captured = new java.util.ArrayList<>();
+        InMemoryExecutionContext ctx = new InMemoryExecutionContext(t -> {
+            if (t instanceof RecipeError) {
+                captured.add((RecipeError) t);
+            }
+        });
+        rewriteRun(
+          spec -> spec.executionContext(ctx).recipe(new BoomRecipe()),
+          text("hello", "~~(boom)~~>hello")
+        );
+        assertThat(captured).isNotEmpty().allSatisfy(err -> {
+            assertThat(err.getRecipeStack()).containsExactly("org.openrewrite.BoomRecipe");
+            assertThat(err.getSourcePath()).isEqualTo("file.txt");
+            // Cause is RecipeRunException (the visitor's throw site wrapper) which in turn wraps BoomException.
+            assertThat(err.getCause()).isInstanceOf(RecipeRunException.class);
+            assertThat(err.getCause().getCause()).isInstanceOf(BoomException.class);
+        });
+    }
+
+    @Test
+    void onErrorReceivesRecipeErrorWithFullStackForNestedRecipe() {
+        List<RecipeError> captured = new java.util.ArrayList<>();
+        InMemoryExecutionContext ctx = new InMemoryExecutionContext(t -> {
+            if (t instanceof RecipeError) {
+                captured.add((RecipeError) t);
+            }
+        });
+        var parent = new DeclarativeRecipe(
+          "io.example.parent",
+          "Parent recipe",
+          "Parent recipe wrapping a boom child.",
+          emptySet(),
+          null,
+          URI.create("dummy:recipe.yml"),
+          false,
+          emptyList()
+        );
+        parent.addUninitialized(new BoomRecipe());
+        parent.initialize(emptyList());
+        rewriteRun(
+          spec -> spec.executionContext(ctx).recipe(parent),
+          text("hello", "~~(boom)~~>hello")
+        );
+        assertThat(captured).isNotEmpty().allSatisfy(err -> {
+            assertThat(err.getRecipeStack())
+              .containsExactly("io.example.parent", "org.openrewrite.BoomRecipe");
+            assertThat(err.getRecipeName()).isEqualTo("org.openrewrite.BoomRecipe");
+            assertThat(err.getSourcePath()).isEqualTo("file.txt");
+        });
+    }
+
+    @Test
+    void onErrorWrapsErrorsThrownDuringGenerate() {
+        List<RecipeError> captured = new java.util.ArrayList<>();
+        InMemoryExecutionContext ctx = new InMemoryExecutionContext(t -> {
+            if (t instanceof RecipeError) {
+                captured.add((RecipeError) t);
+            }
+        });
+        rewriteRun(
+          spec -> spec.executionContext(ctx).recipe(new BoomGenerateRecipe(false))
+        );
+        assertThat(captured)
+          .singleElement()
+          .satisfies(err -> {
+              assertThat(err.getRecipeStack()).containsExactly("org.openrewrite.BoomGenerateRecipe");
+              assertThat(err.getSourcePath()).isEqualTo("error during generation");
+              assertThat(err.getCause()).isInstanceOf(BoomException.class);
+          });
+    }
+
     @Test
     void exceptionDuringGenerate() {
         rewriteRun(

rewrite-test/src/main/java/org/openrewrite/test/RewriteTest.java

@@ -704,8 +704,9 @@ default void rewriteRun(SourceSpec<?>... sources) {
 
     default ExecutionContext defaultExecutionContext(SourceSpec<?>[] sourceSpecs) {
         InMemoryExecutionContext ctx = new InMemoryExecutionContext(t -> {
-            if (t instanceof RecipeRunException) {
-                fail("Failed to run recipe at " + ((RecipeRunException) t).getCursor(), t);
+            Throwable underlying = t instanceof RecipeError ? t.getCause() : t;
+            if (underlying instanceof RecipeRunException) {
+                fail("Failed to run recipe at " + ((RecipeRunException) underlying).getCursor(), t);
             }
             fail("Failed to parse sources or run recipe", t);
         });