# Helm Upgrade Failed After v1.25 Due to PDB API
> Helm upgrade failed after moving to Kubernetes v1.25? Here’s how I fixed it by cleaning up legacy PDB API references using helm-mapkubeapis.

Canonical: https://blog.abhimanyu-saharan.com/posts/helm-upgrade-failed-after-v1-25-due-to-pdb-api
Published: 2025-05-10
Last updated: 2025-05-24
Authors: Abhimanyu Saharan
Categories: Kubernetes

We recently started upgrading one of our oldest Kubernetes clusters. This cluster had been running reliably on **v1.19** for years without issue. Now that we’re preparing to bring it up to **v1.31**, we decided to step through the intermediate versions. Everything was smooth—until we hit **v1.25**.

That’s when Helm threw an unexpected error and blocked the upgrade:

```sh
Error: UPGRADE FAILED: resource mapping not found for name: "<object-name>" namespace: "<object-namespace>" from "": no matches for kind "PodDisruptionBudget" in version "policy/v1beta1"
ensure CRDs are installed first
```

No application code had changed. The chart logic was untouched. Just the Kubernetes version was bumped. So what happened?

## The Gotcha: Removed API in Helm Metadata

We had overlooked one detail: one of our internal Helm charts still referenced the **PodDisruptionBudget (PDB)** API version `policy/v1beta1`, which was **removed** in Kubernetes **v1.25**.

Even after we corrected the chart to use the updated `policy/v1` API, the upgrade still failed. That’s because Helm’s release metadata was still referencing the removed API.

Helm keeps track of all resources associated with a release, and if one of them refers to an API version that no longer exists in the cluster, it refuses to proceed.

## Enter: `helm-mapkubeapis`

[`helm-mapkubeapis`](https://github.com/helm/helm-mapkubeapis) is a Helm plugin built specifically to address this issue. It scans Helm release metadata for deprecated or removed Kubernetes APIs and updates them in-place to supported versions.

### Installation

```sh
helm plugin install https://github.com/helm/helm-mapkubeapis
```

> IMPORTANT
> Be sure to install **v0.4.1 or later**, as earlier versions don’t fully support resource removal.

## How I Fixed the Problem

Once the plugin was installed, I followed these two steps:

### 1. Dry Run

Check what changes would be applied:

```sh
helm mapkubeapis --dry-run <release-name> --namespace <namespace>
```

The plugin correctly identified the `policy/v1beta1` reference in the metadata.

### 2. Apply the Rewrite

Update the release metadata in-place:

```sh
helm mapkubeapis <release-name> --namespace <namespace>
```

A new release revision was created with the corrected references—and the Helm upgrade succeeded.

## Important: Update Your Charts Too

The plugin fixes Helm’s internal records, but your actual chart templates still need to be updated manually. Here’s the change we made:

```yaml
# BEFORE
apiVersion: policy/v1beta1
kind: PodDisruptionBudget

# AFTER
apiVersion: policy/v1
kind: PodDisruptionBudget
```

Make sure all of your manifests—Deployments, CRDs, PDBs—use API versions supported by your cluster.

## Key Takeaways

- Kubernetes **v1.25** removes `policy/v1beta1`, not just deprecates it.
- Helm stores API references from past releases. Even if your charts are up to date, metadata can block upgrades.
- Use `helm-mapkubeapis` to rewrite Helm release history safely and unblock upgrades.

We’ve now added this plugin to our standard upgrade procedure to avoid similar issues in future migrations.

Have you hit similar snags upgrading across Kubernetes versions? I’d love to hear how you handled them.

## FAQ

### Why did our Helm upgrade fail after moving to Kubernetes v1.25?

The failure was due to a reference to the deprecated `policy/v1beta1` PodDisruptionBudget (PDB) API in Helm’s stored release metadata. Kubernetes v1.25 fully removed this API version, causing Helm to block the upgrade, even though the chart templates were updated.

### What is helm-mapkubeapis and how does it help?

`helm-mapkubeapis` is a Helm plugin that scans and rewrites outdated Kubernetes API references stored in Helm release metadata. It updates them to supported versions, allowing upgrades to proceed when removed APIs would otherwise cause errors.

### Does updating the Helm chart templates alone fix the issue?

No. Updating the chart only ensures future deployments use supported APIs. You must also use `helm-mapkubeapis` to rewrite the existing Helm release metadata, which may still reference removed APIs like `policy/v1beta1`.

### What are the steps to use helm-mapkubeapis?

- **Dry run:** Scan the release for deprecated API versions.
- **Apply:** Rewrite the Helm release metadata with supported API versions.

A new release revision is created, resolving the upgrade issue.

### How can we prevent this issue in future Kubernetes upgrades?

Regularly update chart templates to use supported APIs and include `helm-mapkubeapis` in your cluster upgrade process to ensure Helm release metadata is aligned with your cluster’s API versions.