Introduction

Intermittent docker push failures to a private registry running inside Docker Desktop Kubernetes are usually caused by unstable plumbing around the registry, not by the image itself. The upload path crosses Docker, local networking, Kubernetes service routing, registry storage, and often TLS or ingress. The fastest way to fix the issue is to isolate which layer is failing instead of retrying random pushes.

Start by Testing the Registry Directly

A good first step is to bypass ingress and host name mapping so you can see whether the registry itself is stable.

1kubectl get pods,svc,endpoints -n registry
2kubectl logs -n registry deploy/registry --tail=100
3kubectl port-forward -n registry svc/registry 5000:5000
4curl -v http://127.0.0.1:5000/v2/

If the direct port-forward path works reliably, but pushes fail through your usual host name or NodePort, the registry pod is probably fine and the problem is further out in the network path.

Once direct access is up, push a tiny image first:

docker login 127.0.0.1:5000
docker tag busybox:latest 127.0.0.1:5000/test/busybox:debug
docker push 127.0.0.1:5000/test/busybox:debug

Using a tiny image keeps the test focused on basic connectivity and authentication rather than upload size.

Common Failure Sources

Several issues show up frequently in Docker Desktop Kubernetes setups.

TLS and Certificate Trust

If the registry is served over HTTPS with a self-signed or private certificate, Docker must trust that certificate. Browser trust is not enough, because the Docker daemon has its own trust path.

Ingress Limits and Timeouts

Large image layers can fail intermittently when ingress or reverse proxy settings are too small or too strict. Request body size limits and idle timeouts are common culprits.

Registry Storage Problems

The registry writes uploaded blobs to storage before finalizing the manifest. If the pod restarts, the disk is full, or the PVC is misconfigured, pushes may fail midway with errors such as 500, EOF, or blob upload unknown.

DNS or Routing Weirdness

A local host name may resolve differently from the host operating system, from Docker Desktop internals, or from Kubernetes itself. That can make a registry appear flaky only on some requests.

Authentication State

Bad credential helper state, token expiry, or mismatched auth configuration can produce failures that look random because some layers are reused while others need a fresh upload.

Watch the Logs During a Failed Push

Do not debug only from the Docker client output. Follow the registry logs while reproducing the issue:

kubectl logs -n registry deploy/registry -f

Registry logs often tell you whether the failure happened during:

• authentication
• blob upload
• manifest commit
• filesystem write
• backend storage access

That distinction matters. A timeout in ingress needs a different fix than a write error on the registry volume.

Check the Deployment and Storage

The registry should use persistent storage rather than ephemeral container storage. A minimal deployment looks like this:

1apiVersion: apps/v1
2kind: Deployment
3metadata:
4  name: registry
5  namespace: registry
6spec:
7  replicas: 1
8  selector:
9    matchLabels:
10      app: registry
11  template:
12    metadata:
13      labels:
14        app: registry
15    spec:
16      containers:
17        - name: registry
18          image: registry:2
19          env:
20            - name: REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY
21              value: /var/lib/registry
22          volumeMounts:
23            - name: registry-data
24              mountPath: /var/lib/registry
25      volumes:
26        - name: registry-data
27          persistentVolumeClaim:
28            claimName: registry-pvc

If the registry is writing to temporary container storage, pod restarts can easily break uploads or lose layer data.

A Practical Debug Order

When the failure is intermittent, this order keeps the search tight:

1. test the registry with kubectl port-forward
2. push a very small image directly
3. inspect registry logs during the push
4. test again through ingress or NodePort
5. check TLS trust, ingress limits, and PVC health

That sequence tells you whether the instability is in the registry itself or in the path in front of it.

Common Pitfalls

One common mistake is testing only through ingress and assuming the registry deployment is broken. Often the registry is fine and the real issue is proxy configuration.

Another pitfall is ignoring storage. Pushes that fail halfway through large layers are often storage or timeout problems, not bad image tags.

People also frequently trust a self-signed certificate in the browser and assume Docker will trust it too. The Docker daemon needs its own trust setup.

Finally, intermittent failures are harder to diagnose with large images. Start with a tiny test image, then move to a real workload once the basic path is stable.

Summary

• Intermittent registry pushes are usually caused by networking, TLS, ingress, auth, or storage issues.
• Test the registry directly with kubectl port-forward before debugging the full host name path.
• Watch registry logs during the failed push to locate the real failure stage.
• Make sure the registry uses persistent storage and sane proxy limits.
• Use tiny images first to separate basic connectivity problems from large-upload problems.