kptdev · efiacor · Feb 25, 2026 · Feb 24, 2026 · Feb 25, 2026
@@ -63,8 +63,6 @@ func NewRunner(ctx context.Context, parent string) *Runner {
 		"allow functions to access network during pipeline execution.")
 	c.Flags().BoolVar(&r.RunnerOptions.AllowWasm, "allow-alpha-wasm", r.RunnerOptions.AllowWasm,
 		"allow wasm to be used during pipeline execution.")
-	c.Flags().BoolVar(&r.RunnerOptions.SaveOnRenderFailure, "save-on-render-failure", r.RunnerOptions.SaveOnRenderFailure,
-		"save partially rendered resources when rendering fails.")
 	cmdutil.FixDocs("kpt", parent, c)
 	r.Command = c
 	return r

@@ -88,6 +88,16 @@ YAML as the file format.
 A package is explicitly declared using a file named `Kptfile` containing a KRM resource of kind `Kptfile`. The Kptfile
 contains metadata about the package and is just a regular resource in the YAML format.
 
+### Kptfile Annotations
+
+The Kptfile supports annotations that control package-level behaviour:
+
+- **`kpt.dev/bfs-rendering`**: When set to `"true"`, renders the package hierarchy in breadth-first order instead of
+the default depth-first post-order.
+- **`kpt.dev/save-on-render-failure`**: When set to `"true"`, saves partially rendered resources to disk even when
+rendering fails, instead of reverting all changes. This is particularly useful for debugging render failures and is
+essential for programmatic package rendering scenarios where preserving partial progress is valuable.
+
 Just as directories can be nested, a package can contain another package, called a _subpackage_.
 
 Let's take a look at the wordpress package as an example:

@@ -124,8 +124,38 @@ The end result is that:
 3. Resources in `mysql` and `wordpress` packages are validated against their
    OpenAPI spec.
 
-If any of the functions in the pipeline fails for whatever reason, then the
-entire pipeline is aborted and the local filesystem is left intact.
+### Debugging render failures
+
+When a render pipeline fails, you can configure the package to save partially rendered resources to disk.
+This is particularly useful for debugging function pipeline issues by inspecting what changes were made before
+the failure occurred.
+
+By default, partially rendered resources are not saved when render fails. To enable this behaviour,
+add the `kpt.dev/save-on-render-failure` annotation to the Kptfile's metadata section:
+
+```yaml
+apiVersion: kpt.dev/v1
+kind: Kptfile
+metadata:
+  name: wordpress
+  annotations:
+    kpt.dev/save-on-render-failure: "true"
+pipeline:
+  mutators:
+    - image: ghcr.io/kptdev/krm-functions-catalog/set-labels:latest
+      configMap:
+        app: wordpress
+  validators:
+    - image: ghcr.io/kptdev/krm-functions-catalog/kubeconform:latest
+```
+
+With this annotation set to `"true"`, if a function in the pipeline fails, kpt will save all resources that were
+successfully processed up to the point of failure. This allows you to examine the intermediate state and understand
+what transformations were applied before the error.
+
+This annotation follows the same pattern as `kpt.dev/bfs-rendering` and must be declared in the root package's Kptfile
+before running `kpt fn render`.
+
 
 ### Specifying `function`
 

@@ -74,6 +74,18 @@ PKG_PATH:
   If not specified, no result files are written to the local filesystem.
 ```
 
+#### Kptfile Annotations
+
+```shell
+kpt.dev/save-on-render-failure:
+  Controls whether partially rendered resources are saved when rendering fails.
+  Set to "true" in the Kptfile metadata.annotations section to preserve the state
+  of resources at the point of failure. This is useful for debugging render failures
+  and understanding what changes were applied before the error occurred.
+  This follows the same pattern as kpt.dev/bfs-rendering annotation.
+  Default: false (failures will revert changes).
+```
+
 #### Environment Variables
 
 ```shell
@@ -131,6 +143,17 @@ $ KRM_FN_RUNTIME=podman kpt fn render my-package-dir
 $ kpt fn render --allow-network
 ```
 
+```shell
+# Example Kptfile with save-on-render-failure annotation
+apiVersion: kpt.dev/v1
+kind: Kptfile
+metadata:
+  name: my-package
+  annotations:
+    kpt.dev/save-on-render-failure: "true"
+...
+```
+
 <!--mdtogo-->
 
 [declarative functions execution]:

@@ -1,3 +1,2 @@
 exitCode: 1
-saveOnRenderFailure: true
 StdErrRegEx: "(docker: Error response from daemon: Head.*denied|Error.*initializing source docker)"
@@ -1,11 +1,11 @@
 diff --git a/Kptfile b/Kptfile
-index 2b64f0f..b2b7aa6 100644
+index ec2c042..d795f4f 100644
 --- a/Kptfile
 +++ b/Kptfile
-@@ -3,7 +3,9 @@ kind: Kptfile
- metadata:
+@@ -4,7 +4,9 @@ metadata:
    annotations:
      kpt.dev/bfs-rendering: "true"
+     kpt.dev/save-on-render-failure: "true"
 +    app: myapp
    name: save-on-render-failure
 +  namespace: staging
@@ -28,4 +28,4 @@ index 0848ba0..7eece9b 100644
 +  template:
 +    metadata:
 +      annotations:
-+        app: myapp
++        app: myapp
@@ -3,6 +3,7 @@ kind: Kptfile
 metadata:
   annotations:
     kpt.dev/bfs-rendering: "true"
+    kpt.dev/save-on-render-failure: "true"
   name: save-on-render-failure
 pipeline:
   mutators:

@@ -1,3 +1,2 @@
 exitCode: 1
-saveOnRenderFailure: true
 StdErrRegEx: "(docker: Error response from daemon: Head.*denied|Error.*initializing source docker)"
@@ -1,10 +1,10 @@
 diff --git a/Kptfile b/Kptfile
-index 20f0a00..1129926 100644
+index dbd6541..bc4fd2d 100644
 --- a/Kptfile
 +++ b/Kptfile
-@@ -4,10 +4,12 @@ metadata:
-   annotations:
+@@ -5,10 +5,12 @@ metadata:
      kpt.dev/bfs-rendering: "true"
+     kpt.dev/save-on-render-failure: "true"
    name: bfs-deep-nested-middle-fails
 +  labels:
 +    level: root
@@ -82,4 +82,4 @@ index ab7d3fa..1eeeaed 100644
 +  labels:
 +    level: level1
  data:
-   level: level2
+   level: level2
@@ -3,6 +3,7 @@ kind: Kptfile
 metadata:
   annotations:
     kpt.dev/bfs-rendering: "true"
+    kpt.dev/save-on-render-failure: "true"
   name: bfs-deep-nested-middle-fails
 info:
   description: BFS - Deep nested, middle level fails

@@ -1,3 +1,2 @@
 exitCode: 1
-saveOnRenderFailure: true
 StdErrRegEx: "(docker: Error response from daemon: Head.*denied|Error.*initializing source docker)"
@@ -1,10 +1,10 @@
 diff --git a/Kptfile b/Kptfile
-index 436929b..101eb46 100644
+index e9fad85..1b08a62 100644
 --- a/Kptfile
 +++ b/Kptfile
-@@ -4,6 +4,8 @@ metadata:
-   annotations:
+@@ -5,6 +5,8 @@ metadata:
      kpt.dev/bfs-rendering: "true"
+     kpt.dev/save-on-render-failure: "true"
    name: bfs-multiple-subpkgs-one-fails
 +  labels:
 +    pkg: root
@@ -121,4 +121,4 @@ index dc257b3..3a13d11 100644
 +  template:
 +    metadata:
 +      labels:
-+        pkg: root
++        pkg: root
@@ -3,6 +3,7 @@ kind: Kptfile
 metadata:
   annotations:
     kpt.dev/bfs-rendering: "true"
+    kpt.dev/save-on-render-failure: "true"
   name: bfs-multiple-subpkgs-one-fails
 info:
   description: BFS - Multiple subpackages, sub2 fails

@@ -1,3 +1,2 @@
 exitCode: 1
-saveOnRenderFailure: true
 StdErrRegEx: "(docker: Error response from daemon: Head.*denied|Error.*initializing source docker)"
@@ -1,10 +1,10 @@
 diff --git a/Kptfile b/Kptfile
-index 542177a..a19bbc4 100644
+index cbe756f..a5fa6c0 100644
 --- a/Kptfile
 +++ b/Kptfile
-@@ -4,6 +4,8 @@ metadata:
-   annotations:
+@@ -5,6 +5,8 @@ metadata:
      kpt.dev/bfs-rendering: "true"
+     kpt.dev/save-on-render-failure: "true"
    name: bfs-parent-and-subpkg-both-fail
 +  labels:
 +    pkg: root
@@ -50,4 +50,4 @@ index 276bf9e..d6424da 100644
    ports:
    - port: 80
 +  selector:
-+    pkg: root
++    pkg: root
@@ -3,6 +3,7 @@ kind: Kptfile
 metadata:
   annotations:
     kpt.dev/bfs-rendering: "true"
+    kpt.dev/save-on-render-failure: "true"
   name: bfs-parent-and-subpkg-both-fail
 info:
   description: BFS - Both parent and subpackage fail

@@ -1,3 +1,2 @@
 exitCode: 1
-saveOnRenderFailure: true
 StdErrRegEx: "(docker: Error response from daemon: Head.*denied|Error.*initializing source docker)"
@@ -1,10 +1,10 @@
 diff --git a/Kptfile b/Kptfile
-index 2391a7a..0e48609 100644
+index c80b904..6954e67 100644
 --- a/Kptfile
 +++ b/Kptfile
-@@ -4,11 +4,13 @@ metadata:
-   annotations:
+@@ -5,11 +5,13 @@ metadata:
      kpt.dev/bfs-rendering: "true"
+     kpt.dev/save-on-render-failure: "true"
    name: bfs-parent-mutator-fails
 +  labels:
 +    test: parent-mutator-fail
@@ -56,4 +56,4 @@ index 276bf9e..acfae7a 100644
    ports:
    - port: 80
 +  selector:
-+    test: parent-mutator-fail
++    test: parent-mutator-fail
@@ -3,6 +3,7 @@ kind: Kptfile
 metadata:
   annotations:
     kpt.dev/bfs-rendering: "true"
+    kpt.dev/save-on-render-failure: "true"
   name: bfs-parent-mutator-fails
 info:
   description: BFS - Parent mutator fails

@@ -1,3 +1,2 @@
 exitCode: 1
-saveOnRenderFailure: true
 StdErrRegEx: "(docker: Error response from daemon: Head.*denied|Error.*initializing source docker)"
@@ -1,10 +1,10 @@
 diff --git a/Kptfile b/Kptfile
-index 3e37f10..87a67b1 100644
+index 491b12e..8c66fe7 100644
 --- a/Kptfile
 +++ b/Kptfile
-@@ -4,12 +4,14 @@ metadata:
-   annotations:
+@@ -5,12 +5,14 @@ metadata:
      kpt.dev/bfs-rendering: "true"
+     kpt.dev/save-on-render-failure: "true"
    name: bfs-parent-validator-fails
 +  labels:
 +    test: parent-fail
@@ -57,4 +57,4 @@ index 276bf9e..fe08496 100644
    ports:
    - port: 80
 +  selector:
-+    test: parent-fail
++    test: parent-fail
@@ -3,6 +3,7 @@ kind: Kptfile
 metadata:
   annotations:
     kpt.dev/bfs-rendering: "true"
+    kpt.dev/save-on-render-failure: "true"
   name: bfs-parent-validator-fails
 info:
   description: BFS - Parent validator fails

@@ -1,3 +1,2 @@
 exitCode: 1
-saveOnRenderFailure: true
 StdErrRegEx: "(docker: Error response from daemon: Head.*denied|Error.*initializing source docker)"
@@ -1,10 +1,10 @@
 diff --git a/Kptfile b/Kptfile
-index 95a1035..aa44f54 100644
+index 84b93a6..877725d 100644
 --- a/Kptfile
 +++ b/Kptfile
-@@ -4,10 +4,12 @@ metadata:
-   annotations:
+@@ -5,10 +5,12 @@ metadata:
      kpt.dev/bfs-rendering: "true"
+     kpt.dev/save-on-render-failure: "true"
    name: bfs-subpkg-mutator-fails
 +  labels:
 +    test: mutator-fail
@@ -68,4 +68,4 @@ index 302322e..546fe5c 100644
 +  template:
 +    metadata:
 +      labels:
-+        test: mutator-fail
++        test: mutator-fail
@@ -3,6 +3,7 @@ kind: Kptfile
 metadata:
   annotations:
     kpt.dev/bfs-rendering: "true"
+    kpt.dev/save-on-render-failure: "true"
   name: bfs-subpkg-mutator-fails
 info:
   description: BFS - Subpackage mutator fails

@@ -1,3 +1,2 @@
 exitCode: 1
-saveOnRenderFailure: true
 StdErrRegEx: "(docker: Error response from daemon: Head.*denied|Error.*initializing source docker)"
@@ -1,10 +1,10 @@
 diff --git a/Kptfile b/Kptfile
-index 35b7419..08a35b8 100644
+index 86dbe13..c5c38b8 100644
 --- a/Kptfile
 +++ b/Kptfile
-@@ -4,11 +4,14 @@ metadata:
-   annotations:
+@@ -5,11 +5,14 @@ metadata:
      kpt.dev/bfs-rendering: "true"
+     kpt.dev/save-on-render-failure: "true"
    name: bfs-subpkg-validator-fails
 +  labels:
 +    level: root
@@ -78,4 +78,4 @@ index 302322e..dfe3056 100644
 +    metadata:
 +      labels:
 +        level: root
-+        test: subpkg-fail
++        test: subpkg-fail
@@ -3,6 +3,7 @@ kind: Kptfile
 metadata:
   annotations:
     kpt.dev/bfs-rendering: "true"
+    kpt.dev/save-on-render-failure: "true"
   name: bfs-subpkg-validator-fails
 info:
   description: BFS - Subpackage validator fails

@@ -1,3 +1,2 @@
 exitCode: 1
-saveOnRenderFailure: true
 StdErrRegEx: "(docker: Error response from daemon: Head.*denied|Error.*initializing source docker)"
@@ -1,13 +1,13 @@
 diff --git a/Kptfile b/Kptfile
-index a2aef8c..93f2bd5 100644
+index c6fc0c5..1631bfb 100644
 --- a/Kptfile
 +++ b/Kptfile
-@@ -2,6 +2,9 @@ apiVersion: kpt.dev/v1
- kind: Kptfile
+@@ -3,7 +3,9 @@ kind: Kptfile
  metadata:
-   name: save-on-render-failure
-+  annotations:
+   annotations:
+     kpt.dev/save-on-render-failure: "true"
 +    app: myapp
+   name: save-on-render-failure
 +  namespace: staging
  pipeline:
    mutators: