Troubleshooting Getting Started

Overview

This section contains solutions to common problems that you might encounter while installing, configuring, and updating Minishift.

GitHub API rate limit exceeded

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 oc.

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:

  1. Error starting the cluster: Error attempting to download and cache oc: Cannot get the OpenShift
  2. release version v3.6.0: GET https://api.github.com/repos/openshift/origin/releases/tags/v3.6.0:
  3. 403 API rate limit exceeded for (your IP shows here). (But here's the good news: Authenticated
  4. requests get a higher rate limit. Check out the documentation for more details.); rate reset in
  5. 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:

  1. $ export MINISHIFT_GITHUB_API_TOKEN=<token_ID>

Replace <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.

Minishift startup check failed

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:

    1. $ minishift config set skip-startup-checks true

The following sections describe the different startup checks.

Driver plug-in configuration

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:

    1. $ minishift config set warn-check-kvm-driver true

  • For xhyve on macOS, run the following command:

    1. $ minishift config set warn-check-xhyve-driver true

  • For Hyper-V on Windows, run the following command:

    1. C:\> minishift.exe config set warn-check-hyperv-driver true

Persistent storage volume configuration and usage

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:

  1. $ minishift config set skip-check-storage-usage true

External network connectivity

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:

  1. $ minishift config set check-network-ping-host <host-IP-address>

Replace <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:

  1. $ minishift config set check-network-http-host <URL>

Permission denied error when updating Minishift

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).

  1. $ which minishift
  2. /usr/bin/minishift
  4. $ minishift update
  5. A newer version of minishift is available.
  6. Do you want to update from 1.1.0 to 1.2.0 now? [y/N]: y
  7. Downloading https://github.com/minishift/minishift/releases/download/v1.2.0/minishift-1.2.0-linux-amd64.tgz
  8.  3.68 MiB / 3.68 MiB [===========================================================================================================================================] 100.00% 0s
  9.  65 B / 65 B [===================================================================================================================================================] 100.00% 0s
  10. Update failed: open /usr/bin/.minishift.new: permission denied

OpenShift web console does not work with older versions of Safari

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:

  1. 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.