Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Kubernetes in Docker Desktop will not start or stays on starting

ErrorKubernetes status in Docker Desktop stays at starting and never reaches running

Short answer

When the Docker Desktop cluster hangs on starting, the usual causes are too few resources, a broken cluster state, or the kubeadm provisioner failing. Raise resources, use Reset cluster, and if needed switch between kubeadm and kind. If only kubectl complains, select the docker-desktop context.

  • Applies to Docker Desktop 4.x for Mac and Windows, kubectl 1.3x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check whether kubectl sees the docker-desktop context and whether the Kubernetes system containers exist. Turn on Show system containers (advanced) first if the second list is empty.

    kubectl config get-contexts
    docker ps -a
  2. 2Match what you see, then jump to its fix

    1. 1The cluster starts slowly, then stops, and the machine or the Docker VM is tight on memoryDocker Desktop has too few resourcesFix
    2. 2Kubernetes worked before an update or a crash and now hangs on startingThe cluster state is corrupted or stale after an updateFix
    3. 3Reset does not help and the cluster still never becomes readyThe kubeadm provisioner will not start on this machineFix
    4. 4Docker Desktop shows Kubernetes running, but kubectl prints errors or lists no contextskubectl points at another context or cannot find the configFix

What does the error look like?

  • Kubernetes status in Docker Desktop stays at starting and never reaches running
  • kubectl shows no contexts, or errors against the docker-desktop context
  • The cluster broke after a Docker Desktop update

Cause 1 of 4

Docker Desktop has too few resources

1Check

Open Settings > Resources and compare the memory and CPU allotted to Docker with what the cluster, plus your other containers, need.

docker info --format '{{.NCPU}} CPUs, {{.MemTotal}} bytes'

2Fix

Raise memory and CPU in Settings > Resources, apply, and restart Docker Desktop. Stop containers you do not need.

docker stop $(docker ps -q)

3Verify

Kubernetes reports running and the node is ready.

kubectl get nodes

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 4

The cluster state is corrupted or stale after an update

1Check

Docker documents Reset cluster for misconfigurations, corrupted data and stuck resources. Check the logs of the Kubernetes system containers (Show system containers must be on).

docker ps -a

2Fix

In Settings > Kubernetes choose Reset cluster. If that does not help, use clean and purge data, then restart Docker Desktop. Resetting deletes workloads inside the cluster.

# Settings > Kubernetes > Reset cluster

3Verify

The status turns to running and the node list answers.

kubectl get nodes

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 4

The kubeadm provisioner will not start on this machine

1Check

Docker Desktop can provision the cluster with kubeadm (one node, about a minute) or with kind (multi-node, about 30 seconds, version selectable). Check which one Settings > Kubernetes shows.

kubectl config get-contexts

2Fix

Use Edit cluster in Settings > Kubernetes and switch the provisioner, then apply and restart.

# Settings > Kubernetes > Edit cluster > choose kind or kubeadm

3Verify

The new cluster comes up.

kubectl get nodes

Confirmed by docs.docker.com

Did this fix it?

Cause 4 of 4

kubectl points at another context or cannot find the config

1Check

kubectl may be using another cluster's context. On Windows, run it from Command Prompt or PowerShell; if no contexts appear, set KUBECONFIG to your .kube/config file.

kubectl config current-context

2Fix

Switch to the Docker Desktop context.

kubectl config use-context docker-desktop

3Verify

The node of the Docker Desktop cluster is listed.

kubectl get nodes

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Give Docker Desktop enough memory before enabling Kubernetes, and do not run heavy builds beside it.
  • Keep manifests in files, so resetting the cluster costs one apply.
  • After a Docker Desktop update, check the cluster status before starting work.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.