Helm OCI Registry Push Failed - Fix "helm push" Auth in CI

By Daniel Zoghalchali·Latchkey

Helm can store charts as OCI artifacts, but helm push to an OCI registry needs a prior helm registry login and the correct oci:// reference. A missing login, a wrong URL form, or a registry that rejects the media type fails the push.

What this error means

helm push chart.tgz oci://... fails with unauthorized, denied, or not a valid reference. Pulls/pushes work for container images but the Helm push is rejected - usually an auth or reference issue specific to the Helm OCI flow.

helm output

Error: failed to push chart: unexpected status from PUT request to
https://registry.example.com/v2/charts/api/blobs/uploads/...: 401 Unauthorized
# or
Error: invalid_reference: invalid tag

Diagnose it: render the chart before you install it

Most Helm failures are visible in the rendered manifests. Template them locally with the same values CI uses and you will usually see the problem without touching the cluster.

Terminal

# what will actually be applied
helm template <release> <chart> -f values.ci.yaml | head -60

# validate against the live cluster schema without installing
helm install <release> <chart> -f values.ci.yaml --dry-run --debug

# what state is the release actually in?
helm history <release>
helm status <release>

Common causes

Not logged in to the OCI registry

helm push reuses the registry credentials from helm registry login. Without a successful login (separate from docker login in some setups), the push is unauthorized.

Wrong oci:// reference form

The push target is the repository path without the chart name/version (Helm appends them from the chart). A trailing chart name, a missing oci:// scheme, or an unsupported tag breaks the reference.

How to fix it

Log in, then push to the repository path

Authenticate to the registry and push to the oci://<registry>/<repo> path (Helm derives the chart name and version from the package).

Terminal

echo "$REG_TOKEN" | helm registry login registry.example.com \
  --username "$REG_USER" --password-stdin
helm package ./chart            # produces api-1.2.3.tgz
helm push api-1.2.3.tgz oci://registry.example.com/charts

Confirm registry OCI support and reference

Ensure the registry supports OCI Helm artifacts (most modern ones do).
Use the oci:// scheme and a repository path without the chart filename.
Verify by pulling it back: helm pull oci://registry.example.com/charts/api --version 1.2.3.

How to prevent it

Run helm registry login before helm push in CI.
Push to the oci://<registry>/<repo> path and let Helm append name:version.
Round-trip with helm pull to confirm the artifact is retrievable.

Frequently asked questions

What causes Helm OCI registry push failed?

There are 2 common causes: not logged in to the oci registry and wrong oci:// reference form. helm push reuses the registry credentials from helm registry login.

How do I fix Helm OCI registry push failed?

There are 2 fixes depending on which cause you have: log in, then push to the repository path and confirm registry oci support and reference. Work through them in order, since the first is the most common.

What does Helm OCI registry push failed actually mean?

helm push chart.tgz oci://...

How do I stop Helm OCI registry push failed happening again?

Run helm registry login before helm push in CI. The prevention section lists 3 changes that keep it from recurring.