Version: 2.11

View Detailed Restore Failures from the Backup Location

For large resource-based restores, detailed resource information is not retained in the restore object or displayed in the Portworx Backup UI. In case of a partial restore, Portworx Backup stores a copy of the Restore Custom Resource (restore CR) as a JSON file in the backup location. You can review this file to identify per-resource status and failure reasons.

note

A partial restore status indicates that one or more resources failed during the restore process. It does not indicate that resources were skipped or retained due to user-defined retain policies.
To verify whether a non-large backup is treated as a large resource-based restore, check the Stork logs for the following message:
```
Stripping all the resource info from restore cr as it is a large resource based restore.
```
You can also verify this by checking the corresponding flag in the restore object.

Restore CR File Storage Location

Depending on the backup location type, the restore CR file is stored in:

S3:

<bucket-name>/restore-crs/<restore-cr-name>-<shortUID>.json
NFS:

<export-path>/<sub-path>/restore-crs/<restore-cr-name>-<shortUID>.json

In NFS locations, <sub-path> refers to the optionally configured subdirectory within the export path.

important
The restore CR file is deleted after you delete the corresponding restore object using the Portworx Backup UI or CLI. For object lock–enabled backup locations, the restore CR file is deleted automatically after the retention period expires.

Identifying Failed Resources in Large Restores

To identify the failed resources, follow these steps:

Open the restore CR JSON file and locate the following section:

status.resources[]

Each resource entry includes a status and reason field:
- If status is Successful, the resource was restored successfully.
- If status is Failed, review the reason field to identify the exact error.
Check for the following reason string for the "status": "Failed".

"Error applying resource: STUB: simulated failure for resource test-secret9 as configured in stubResourcesToFail"

The Error applying resource indicates the resouce failed to restore in a large resource restore.

Sample Restore CR JSON

This is a sample JSON file for documentation purpose only to show the success and failed resources.

{
  "metadata": {
    "name": "n2-85d1556",
    "namespace": "kube-system",
    "uid": "898XXXXX-abcd-cbcd-8b16-f03a59c0b77f",
    "resourceVersion": "329877",
    "generation": 6,
    "creationTimestamp": "2026-01-28T03:58:59Z",
    "labels": {
      "app.kubernetes.io/part-of": "px-backup"
    },
    "annotations": {
      "portworx.io/cluster-name": "local-clu",
      "portworx.io/cluster-uid": "fceXXXXX-abcd-abcd-b3fb-ed972fdXXXXXX",
      "portworx.io/created-by": "px-backup",
      "portworx.io/last-update": "2026-01-28T03:58:59.055573928Z",
      "portworx.io/org-id": "default",
      "portworx.io/restore-name": "n2",
      "portworx.io/restore-uid": "85d1XXXXX-abcd-abcd-86ff-72f3e397d430"
    },
    "finalizers": [
      "stork.libopenstorage.org/finalizer-cleanup"
    ],
    "managedFields": [
      {
        "manager": "px-backup",
        "operation": "Update",
        "apiVersion": "stork.libopenstorage.org/v1alpha1",
        "time": "2026-01-28T03:58:59Z",
        "fieldsType": "FieldsV1",
        "fieldsV1": {
          "f:metadata": {
            "f:annotations": {
              ".": {},
              "f:portworx.io/cluster-name": {},
              "f:portworx.io/cluster-uid": {},
              "f:portworx.io/created-by": {},
              "f:portworx.io/last-update": {},
              "f:portworx.io/org-id": {},
              "f:portworx.io/restore-name": {},
              "f:portworx.io/restore-uid": {}
            },
            "f:labels": {
              ".": {},
              "f:app.kubernetes.io/part-of": {}
            }
          },
          "f:spec": {
            ".": {},
            "f:backupLocation": {},
            "f:backupName": {},
            "f:backupObjectType": {},
            "f:filter": {
              ".": {},
              "f:namespaceFilter": {
                ".": {},
                "f:includeNamespaces": {}
              }
            },
            "f:includeOptionalResourceTypes": {},
            "f:includeResources": {},
            "f:isSFR": {},
            "f:keepCrStatus": {},
            "f:namespaceMapping": {
              ".": {},
              "f:cm-ns": {},
              "f:secret-ns": {}
            },
            "f:rancherProjectMapping": {},
            "f:replacePolicy": {},
            "f:storageClassMapping": {},
            "f:virtualMachineFiles": {},
            "f:virtualMachineName": {},
            "f:vmRestoreOptions": {
              ".": {},
              "f:skipMacMasking": {},
              "f:skipVmRestart": {}
            }
          },
          "f:status": {
            ".": {},
            "f:finishTimestamp": {},
            "f:largeResourceEnabled": {},
            "f:resourceCount": {},
            "f:resourcerestorestate": {},
            "f:resources": {},
            "f:restoredresourceCount": {},
            "f:singleFileRestoreStatus": {
              ".": {},
              "f:failedFiles": {},
              "f:files": {},
              "f:finishTimestamp": {},
              "f:lastUpdateTimestamp": {},
              "f:reason": {},
              "f:status": {},
              "f:totalFiles": {}
            },
            "f:totalSize": {}
          }
        }
      },
      {
        "manager": "stork",
        "operation": "Update",
        "apiVersion": "stork.libopenstorage.org/v1alpha1",
        "time": "2026-01-28T03:59:29Z",
        "fieldsType": "FieldsV1",
        "fieldsV1": {
          "f:metadata": {
            "f:finalizers": {
              ".": {},
              "v:\"stork.libopenstorage.org/finalizer-cleanup\"": {}
            }
          },
          "f:status": {
            "f:lastUpdateTimestamp": {},
            "f:reason": {},
            "f:stage": {},
            "f:status": {},
            "f:volumes": {}
          }
        }
      }
    ]
  },
  "spec": {
    "backupName": "bkp-cm-secret-nfs-85d1556",
    "backupLocation": "test-nfs-bl-85d1556",
    "namespaceMapping": {
      "cm-ns": "n2-cm",
      "secret-ns": "n2-secret"
    },
    "replacePolicy": "Delete",
    "includeOptionalResourceTypes": null,
    "includeResources": null,
    "storageClassMapping": null,
    "rancherProjectMapping": null,
    "backupObjectType": "All",
    "keepCrStatus": false,
    "vmRestoreOptions": {
      "skipMacMasking": false,
      "skipVmRestart": false
    },
    "filter": {
      "namespaceFilter": {
        "includeNamespaces": [
          "cm-ns",
          "secret-ns"
        ]
      }
    },
    "isSFR": false,
    "virtualMachineName": "",
    "virtualMachineFiles": null
  },
  "status": {
    "stage": "Applications",
    "status": "InProgress",
    "reason": "Application resources restore is in progress",
    "resources": [
      {
        "name": "test86",
        "namespace": "n2-cm",
        "group": "",
        "version": "v1",
        "kind": "ConfigMap",
        "status": "Successful",
        "reason": "Resource restored successfully"
      },
      {
        "name": "test87",
        "namespace": "n2-cm",
        "group": "",
        "version": "v1",
        "kind": "ConfigMap",
        "status": "Successful",
        "reason": "Resource restored successfully"
      },
      {
        "name": "test88",
        "namespace": "n2-cm",
        "group": "",
        "version": "v1",
        "kind": "ConfigMap",
        "status": "Successful",
        "reason": "Resource restored successfully"
      },
      {
        "name": "test89",
        "namespace": "n2-cm",
        "group": "",
        "version": "v1",
        "kind": "ConfigMap",
        "status": "Failed",
        "reason": "Error applying resource: STUB: simulated failure for resource test89 as configured in stubResourcesToFail"
      },
      {
        "name": "test-secret30",
        "namespace": "n2-secret",
        "group": "",
        "version": "v1",
        "kind": "Secret",
        "status": "Failed",
        "reason": "Error applying resource: STUB: simulated failure for resource test-secret30 as configured in stubResourcesToFail"
      },
      {
        "name": "test-secret9",
        "namespace": "n2-secret",
        "group": "",
        "version": "v1",
        "kind": "Secret",
        "status": "Failed",
        "reason": "Error applying resource: STUB: simulated failure for resource test-secret9 as configured in stubResourcesToFail"
      }
    ],
    "volumes": [],
    "finishTimestamp": null,
    "lastUpdateTimestamp": "2026-01-28T03:59:29Z",
    "totalSize": 0,
    "resourceCount": 0,
    "largeResourceEnabled": false,
    "restoredresourceCount": 0,
    "resourcerestorestate": "",
    "singleFileRestoreStatus": {
      "status": "",
      "reason": "",
      "files": null,
      "finishTimestamp": null,
      "lastUpdateTimestamp": null,
      "totalFiles": 0,
      "failedFiles": 0
    }
  }
}

Metadata Fields

Field	Description	Example
`metadata.name`	Name of the restore custom resource	`n2-85d1556`
`metadata.namespace`	Kubernetes namespace where the restore CR exists	`kube-system`
`metadata.uid`	Unique identifier assigned by Kubernetes to the restore object	`898XXXXX-abcd-cbcd-8b16-f03a59c0b77f`
`metadata.res Version`	Internal Kubernetes version used for object change tracking	`329877`
`metadata.generation`	Number of times the desired spec has changed	`6`
`metadata.creationTimestamp`	Timestamp when the restore CR was created	`2026-01-28T03:58:59Z`
`metadata.labels`	Labels associated with the restore CR	`app.kubernetes.io/part-of: px-backup`
`metadata.annotations`	Additional metadata used by Portworx Backup for restore context	Cluster name, restore name, organization ID

Restore Specification Fields

Field	Description	Example
`spec.backupName`	Name of the backup used for the restore	`bkp-cm-secret-nfs-85d1556`
`spec.backupLocation`	Backup location from which the restore is performed	`test-nfs-bl-85d1556`
`spec.namespaceMapping`	Mapping of source namespaces to destination namespaces	`cm-ns → n2-cm`, `secret-ns → n2-secret`
`spec.replacePolicy`	Defines how existing resources are handled during restore	`Delete`
`spec.includeOptionalResourceTypes`	Optional resource types included in restore	`null`
`spec.includeResources`	Specific resources selected for restore	`null`
`spec.storageClassMapping`	Mapping of source storage classes to destination storage classes	`null`
`spec.rancherProjectMapping`	Rancher project mapping used during restore	`null`
`spec.backupObjectType`	Type of backup object being restored	`All`
`spec.keepCrStatus`	Indicates whether restore CR status should be retained	`false`
`spec.filter.namespaceFilter.includeNamespaces`	Namespaces selected for restore	`cm-ns`, `secret-ns`
`spec.vmRestoreOptions.skipMacMasking`	Skips MAC address masking during VM restore	`false`
`spec.vmRestoreOptions.skipVmRestart`	Skips VM restart after restore	`false`
`spec.virtualMachineName`	Name of VM being restored if VM restore is used	`""`
`spec.virtualMachineFiles`	File paths used for VM file-level restore	`null`
`spec.isSFR`	Indicates whether this is a single-file restore operation	`false`

Restore Status Fields

Field	Description	Example
`status.stage`	Current stage of the restore process	`Applications`
`status.status`	Overall restore status	`InProgress`
`status.reason`	Description of current restore state	`Application resources restore is in progress`
`status.lastUpdateTimestamp`	Timestamp of the most recent status update	`2026-01-28T03:59:29Z`
`status.finishTimestamp`	Timestamp when restore completed	`null`
`status.resourceCount`	Total number of resources processed	`0`
`status.restoredresourceCount`	Number of resources successfully restored	`0`
`status.totalSize`	Total size of restored resources	`0`
`status.largeResourceEnabled`	Indicates whether the restore was treated as a large resource restore	`false`

Individual Resource Restore Status (`status.resources[]`) Fields

Field	Description	Example
`name`	Name of the Kubernetes resource	`test89`
`namespace`	Namespace of the resource	`n2-cm`
`group`	API group of the resource	`""`
`version`	API version of the resource	`v1`
`kind`	Kubernetes resource type	`ConfigMap`
`status`	Restore status of the resource	`Successful` / `Failed`
`reason`	Detailed result or error message for the restore operation	`Resource restored successfully`

Single File Restore Status Fields

Field	Description	Example
`status.singleFileRestoreStatus.status`	Status of file-level restore operation	`""`
`status.singleFileRestoreStatus.reason`	Reason for success or failure	`""`
`status.singleFileRestoreStatus.totalFiles`	Number of files processed in restore	`0`
`status.singleFileRestoreStatus.failedFiles`	Number of files that failed during restore	`0`

Restore CR File Storage Location​

Identifying Failed Resources in Large Restores​

Sample Restore CR JSON​

Metadata Fields​

Restore Specification Fields​

Restore Status Fields​

Individual Resource Restore Status (status.resources[]) Fields​

Single File Restore Status Fields​