This section contains solutions to common problems that you might encounter while using various components of Minishift.

The root filesystem of the Minishift VM exceeds overlay size

Installing additional packages or copying large files to the root filesystem of the Minishift VM might exceed the allocated overlay size and lock the Minishift VM.

Cause: The Minishift VM root filesystem contains core packages that are configured to optimize running the Minishift VM and containers. The available storage on the root filesystem is determined by the overlay size, which is smaller than the total available storage.

Workaround: Avoid installing packages or storing large files in the root filesystem of the Minishift VM. Instead, you can create a sub-directory in the /mnt/sda1/ persistent storage volume or define and mount host folders that can share storage space between the host and the Minishift VM.

If you want to perform development tasks inside the Minishift VM, it is recommended that you use containers, which are stored in persistent storage volumes, and reuse the Minishift Docker daemon.

Special characters cause passwords to fail

Depending on your operating system and shell environment, certain special characters can trigger variable interpolation and therefore cause passwords to fail.

Workaround: When creating and entering passwords, wrap the string with single quotes in the following format: '<password>'

Authentication required to push image to OpenShift integrated Docker registry

If you are using a Fedora, CentOS or RHEL host and you want to push to the OpenShift registry as described in Accessing the OpenShift Docker Registry, you have to use the CentOS ISO. Using the Boot2Docker or Minikube ISO will result in the following authorization error:

$ docker login -u developer -p `oc whoami -t`
Login Succeeded
$ docker pull busybox
$ docker tag busybox
$ docker push
The push refers to a repository []
6a749002dd6a: Preparing
unauthorized: authentication required

The reason is an incompatibility between the Docker client shipped with your host and the Docker daemon which is running inside the Minishift VM.

Workaround: Use the CentOS ISO when using Minishift on Fedora, CentOS or RHEL. For example:

minishift start --iso-url centos

X.509 certificate is valid for,,,,, not

Starting a stopped Minishift VM can produce the following X.509 certificate error:

$ minishift start
-- Checking if requested hypervisor 'kvm' is supported on this platform ... OK
-- Checking the ISO URL ... OK
-- Starting local OpenShift cluster using 'kvm' hypervisor ...
-- Starting Minishift VM ......................... OK
   Error: cannot access master readiness URL
     No log available from "origin" container

   Caused By:
     Error: Get x509: certificate is valid for,,,,, not
Error during 'cluster up' execution: Error starting the cluster.

The reason for the above error is that OpenShift cluster certificates contain the IP of the Minishift VM. The certificates are generated only when Minishift VM is freshly started. After restart, the Minishift VM might be assigned a new IP address and if this happens the certificate become invalid.

Workaround: Delete the existing Minishift VM and start again.

$ minishift delete --force
$ minishift start