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 | The tag you requested no longer exists. Your image list is stale relative to the version you're installing. | 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. |
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) 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. |