What causes "release: not found" in helm/helm?

Run `helm list --all-namespaces -a` to find where the release actually lives, then use that namespace/driver

release: not found

Error message

release: not found

What it means

ErrReleaseNotFound is the storage drivers' sentinel (secret, configmap, sql, memory) for a Get/Update on a release key that does not exist in the backend. It typically reaches users wrapped in a StorageDriverError carrying the release name.

Source

Thrown at pkg/storage/driver/driver.go:29

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 driver

import (
	"errors"
	"fmt"

	"helm.sh/helm/v4/pkg/release"
	rspb "helm.sh/helm/v4/pkg/release/v1"
)

var (
	// ErrReleaseNotFound indicates that a release is not found.
	ErrReleaseNotFound = errors.New("release: not found")
	// ErrReleaseExists indicates that a release already exists.
	ErrReleaseExists = errors.New("release: already exists")
	// ErrInvalidKey indicates that a release key could not be parsed.
	ErrInvalidKey = errors.New("release: invalid key")
	// ErrNoDeployedReleases indicates that there are no releases with the given key in the deployed state
	ErrNoDeployedReleases = errors.New("has no deployed releases")
)

// StorageDriverError records an error and the release name that caused it
type StorageDriverError struct {
	ReleaseName string
	Err         error
}

func (e *StorageDriverError) Error() string {
	return fmt.Sprintf("%q %s", e.ReleaseName, e.Err.Error())
}

View on GitHub (pinned to 2a29f1770b)

Solutions

Run `helm list --all-namespaces -a` to find where the release actually lives, then use that namespace/driver
Make sure HELM_DRIVER and --namespace match the ones used at install time
If the record was truly removed, treat it as a fresh install (Create path / helm install), not an upgrade

Example fix

# before
helm upgrade myapp ./chart -n prod   # release not found
# after
helm list -A | grep myapp            # locate actual namespace
helm upgrade --install myapp ./chart -n <real-namespace>

Defensive patterns

Strategy: try-catch

Validate before calling

rel, err := cfg.Releases.Last(name)
if err != nil && errors.Is(err, driver.ErrReleaseNotFound) {
    // fresh install path
}

Type guard

func releaseExists(cfg *action.Configuration, name string) bool {
    _, err := cfg.Releases.Last(name)
    return err == nil || !errors.Is(err, driver.ErrReleaseNotFound)
}

Try / catch

if _, err := drv.Get(key); err != nil {
    if errors.Is(err, driver.ErrReleaseNotFound) {
        // take the create/install path, or fix namespace/driver config
    }
}

Prevention

Use helm list -A to confirm release location before operating on it
Pin HELM_DRIVER and --namespace consistently in all environments
Use upgrade --install (create-or-update) instead of assuming the release exists

When it happens

Trigger: driver.Get("sh.helm.release.v1.missing.v1") for a release never installed or already uninstalled; querying the wrong namespace (storage is namespace-scoped); using a different HELM_DRIVER than the one the release was stored with.

Common situations: helm upgrade --install where the lookup assumes an existing release; HELM_NAMESPACE mismatch between install and later commands; release records (secrets) deleted manually in the cluster; switching storage backends (secret -> sql) without migrating releases.

Related errors

AI-assisted analysis of helm/helm@2a29f1770b (2026-08-15). Data as JSON: /api/errors/2f3af5fa9e4f4edd. Report an issue: GitHub.