Troubleshooting Getting Started
This section contains solutions to common problems that you might encounter while installing, configuring, and updating Minishift.
When you run
minishift start or
minishift update, it makes requests to the GitHub API to check for and potentially download new versions of Minishift or the OpenShift client tool
Sometimes, during these requests, you might receive a 403 forbidden status from GitHub if your request exceeds the rate limit for your IP address. In this case, the command will fail and you will receive an error message. For example:
Error starting the cluster: Error attempting to download and cache oc: Cannot get the OpenShift release version v3.6.0: GET https://api.github.com/repos/openshift/origin/releases/tags/v3.6.0: 403 API rate limit exceeded for (your IP shows here). (But here's the good news: Authenticated requests get a higher rate limit. Check out the documentation for more details.); rate reset in 17m2.462768522s
GitHub has a rate limiting policy, see Rate Limiting. You may have reached this limit for various reasons. For example, your package manager may use GitHub API calls or you are behind a corporate network that makes a lot of GitHub unauthenticated API calls.
Instead of waiting for GitHub to reset the limit for your IP address, you can create a Personal API Tokens from your GitHub account. This gives you a higher rate limit.
After you generate the API token, you need to set the
MINISHIFT_GITHUB_API_TOKEN environment variable by running:
$ export MINISHIFT_GITHUB_API_TOKEN=<token_ID>
<token_ID> with your token. You can also add this variable in your shell profile so you don’t need to manually set the variable every time you run a Minishift command.
While Minishift starts, it runs several startup checks to make sure that the Minishift VM and the OpenShift Cluster are able to start without any issues. If any configuration is incorrect or missing, the startup checks fail and Minishift does not start.
You can skip the startup checks by executing the following command:
$ minishift config set skip-startup-checks true
The following sections describe the different startup checks.
One of the startup checks verifies that the relevant driver plug-in is configured correctly. If this startup check fails, review the Setting Up the Virtualization Environment topic and configure the appropriate driver.
If you want to force Minishift to start despite a failing driver plugin-in check, you can instruct Minishift to treat these errors as warnings:
For KVM/Libvirt on Linux, run the following command:
$ minishift config set warn-check-kvm-driver true
For xhyve on macOS, run the following command:
$ minishift config set warn-check-xhyve-driver true
For Hyper-V on Windows, run the following command:
C:\> minishift.exe config set warn-check-hyperv-driver true
Minishift checks whether the persistent storage volume is mounted and that enough disk space is available. If the persistent storage volume, for example, uses more than 95% of the available disk space, Minishift will not start.
If you want to recover the data, you can skip this test and start Minishift to access the persistent volume:
$ minishift config set skip-check-storage-usage true
After the Minishift VM starts, it runs several network checks to verify whether external connectivity is possible from within the Minishift VM.
By default, network checks are configured to treat any errors as warnings, because of the diversity of the development environments. You can configure the network checks to optimize them for your environment.
For example, one of the network checks pings an external host. You can change the host by running the following command:
$ minishift config set check-network-ping-host <host-IP-address>
<host-IP-address> with the address of your internal DNS server, proxy host, or an external host that you can reach from your machine.
Because proxy connectivity might be problematic, you can run a check that tries to retrieve an external URL. You can configure the URL by running:
$ minishift config set check-network-http-host <URL>
When updating Minishift using
minishift update, the update process needs write permissions for the
minishift binary as well as the directory in which it is located. Without these permisions
minishift update will fail. For example, this issue might occur when installing Minishift as root.
Workaround: When updating Minishift, use
sudo minishift update (Linux/macOS).
$ which minishift /usr/bin/minishift $ minishift update A newer version of minishift is available. Do you want to update from 1.1.0 to 1.2.0 now? [y/N]: y Downloading https://github.com/minishift/minishift/releases/download/v1.2.0/minishift-1.2.0-linux-amd64.tgz 3.68 MiB / 3.68 MiB [===========================================================================================================================================] 100.00% 0s 65 B / 65 B [===================================================================================================================================================] 100.00% 0s Update failed: open /usr/bin/.minishift.new: permission denied
minishift console does not work on older versions of Safari web browser such as version 10.1.2 (12603.3.8). Attempting to access the web console results in the following error:
Error unable to load details about the server
Retry after updating it to the latest version or use Firefox or Chrome browser for this. Version 11.0.3 (13604.5.6) has been tested and works with OpenShift web console. You can use
minishift console --url to get the web console URL.