Skip to content

Troubleshooting

Find your message below. Run push with --dry-run first to see names without uploading anything.

Building

failed to pull image: ... MANIFEST_UNKNOWN or 404

The image or tag does not exist on that registry. Check the spelling, and check whether the publisher moved it. For example, Bitnami images that used to be under bitnami/ are now under bitnamilegacy/, so older Bitnami chart versions refer to images that are gone.

failed to pull image: ... UNAUTHORIZED

The image is private. Run docker login <registry> on the build machine. build reads ~/.docker/config.json.

chart <name> not found in repository or chart version <x> not found for <name>

The repo URL is wrong, or that version is not in the repository's index.yaml. List versions with helm search repo <name> --versions after helm repo add.

image is built for linux/arm64, not linux/amd64

The image only exists for another architecture. Build with the matching --platform, or pick an image that supports your target.

invalid platform

--platform takes os/arch or os/arch/variant, for example linux/arm64 or linux/arm/v7.

registry URL is required when rewriting image references

--rewrite-image-references needs --registry-url.

A chart installs, but its pods cannot pull an image

The image is not in the bundle. Capsailer only bundles what the manifest lists. See Finding the images a chart needs.

Pushing

http: server gave HTTP response to HTTPS client, or connection refused on port 443

The registry speaks plain HTTP. Add --plain-http.

x509: certificate signed by unknown authority

The registry uses a certificate your machine does not trust. Add the CA to your system trust store, or for a quick test add --skip-tls-verify.

UNAUTHORIZED or 401

Pass --username and --password-stdin, or run docker login <registry> first. Without --username, credentials come from ~/.docker/config.json. If you use --password-stdin, check that the file or pipe holds only the password.

DENIED or 403, or NAME_UNKNOWN

The user may not push to that path, or the project does not exist. In Harbor, create the project first. If the destination is harbor.example.com/nai/nutanix/nai-api, the project is nai.

N tag(s) would overwrite another image at the same destination; nothing was pushed

Two different images would get the same name. For example quay.io/foo/bar:1 and docker.io/foo/bar:1 both become <registry>/foo/bar:1. Nothing was uploaded. Remove one image from the bundle, or push with --keep-source-registry to keep the source registry in the name. Note that --keep-source-registry makes the names differ from those in charts rewritten by build.

no pushable images found in ...

The archive has no image with a name. Entries without a RepoTag, and images pulled by digest, are skipped. Re-save the images with a tag (docker tag before docker save).

... is not a readable Docker archive

--bundle points to something that is not a docker save file. Check that the file is complete (compare the size and checksum with the source) and is a .tar or .tar.gz.

--dry-run is only supported together with --bundle

Dry run previews a bundle or archive. It does not work with --image.

failed to get registry service or registry service not found in namespace ...

You did not use --external-registry, so push looked for the built-in registry with kubectl. Either run capsailer registry first, check --namespace and --kubeconfig, or add --external-registry <host>.

image ... not found in the local Docker daemon

push --image reads images from your local Docker daemon. Check docker images, and that the daemon is running.

Some images failed but others were pushed

A failure on one image does not stop the others. The command prints each failure and exits with an error at the end. Fix the cause and run the same command again. Existing images are re-checked, and layers the registry already has are not uploaded again.

In the Cluster

ErrImagePull or ImagePullBackOff for a pushed image

Check, in this order:

  1. The name. kubectl describe pod shows the image the pod asks for. It must match a name push printed. Use curl <registry>/v2/_catalog to see what the registry holds.
  2. Reachability. The nodes (not your laptop) must be able to reach the registry address.
  3. HTTP or TLS. If the registry is plain HTTP or has a private CA, the container runtime on every node must be configured to accept it.
  4. Credentials. If the registry needs a login, the pods need an image pull secret.

exec format error in a pod

The node's architecture does not match the bundle. Bundles are linux/amd64 unless built with --platform. Rebuild with --platform linux/arm64 for ARM nodes. See Platform.

The built-in registry cannot be pulled from by name

Node runtimes do not use cluster DNS, so registry.<namespace>.svc.cluster.local does not work for them. Use the service's ClusterIP or a NodePort for --registry-url. See Pulling from the registry.

Unpacking

unpack overwrote my manifest.yaml

unpack extracts into the current directory. Run it in an empty one.

unpack rejects a bundle

Bundles with absolute paths, .. segments or links that point outside the target directory are refused on purpose. Use bundles from capsailer build.