When mirroring or pulling Hybrid Manager artifacts, several unrelated problems can surface as similar-looking errors. This page maps what you see to what's actually happening. For background on the artifact types and registry layout referenced here, see Container registry and artifact reference.
| Symptom | What it actually means | What to do |
|---|---|---|
401 Unauthorized pulling from docker.enterprisedb.com | Your token authenticates, but it doesn't carry access to the pgai-platform namespace. Some subscription tiers grant it and others don't, and a legacy k8s, k8s_enterprise, or k8s_enterprise_pgd subscription doesn't grant it either. Those are separate repositories, so holding one doesn't mean you're entitled to HM images. | Confirm with your EDB account team that your subscription includes pgai-platform access, rather than assuming an existing EDB Kubernetes-product subscription covers it. See Registry credentials. |
missing signature key | Docker Content Trust (DCT) was applied to an OCI artifact (for example, a marketplace Helm chart under kapp-marketplace/). DCT only understands container image signatures. It isn't a security or entitlement failure. | Disable or scope DCT away from the kapp-marketplace/ path, and use an OCI-native client (skopeo, crane, oras, or helm pull oci://) instead of docker pull. |
manifest unknown (CRI-O, for example OpenShift) or not found (containerd) | Either the tag you requested no longer exists (your image list is stale relative to the version you're installing), or the specific digest it's asking for was never pushed to your registry at all. The second case is common after a mirroring tool copied only a single architecture and dropped the multi-architecture index: the index digest HM pins to simply doesn't exist at your destination, even though the single-platform image copied without any reported error. | For a stale tag: re-fetch images.txt for your target version (see Canonical image list). If your registry sits behind a proxy or caching layer, also clear its negative cache. Some default to caching a "not found" result for up to 24 hours.For a missing index: re-copy with Preserving digests, which copies the full multi-architecture index rather than a single platform. |
digest invalid: provided digest did not match uploaded content | The artifact's manifest was altered in transit, most often by a docker pull/push cycle or a proxying registry that re-serializes what passes through it, so its digest no longer matches what was requested. | Re-copy with a digest-preserving tool (skopeo copy --preserve-digests --multi-arch all) and remove any daemon-mediated step from the copy path. See Preserving digests. |
| Authentication error pushing to the OpenShift internal registry | The OpenShift internal registry ties each image path to the project namespace it's pushed from, so a path with more than one segment before the image name doesn't fit. HM's control-plane images need a path that's independent of any namespace, which this registry can't express. | Use <project>/<name>. More generally, the OpenShift internal registry isn't a supported destination for HM images. See Destination registry layout requirements. |
Pod stuck in ImagePullBackOff, and the registry shows no incoming connection at all | The cluster's own image admission policy refused the registry before a pull was attempted. This refusal is a policy failure, not a networking or registry-availability problem. | Check for a blocked = true entry for the registry in /etc/containers/registries.conf on the node, or your platform's equivalent admission-control configuration. See Network access and registry allowlisting. |