Chapter 3. Troubleshooting Red Hat CodeReady Containers


The goal of Red Hat CodeReady Containers is to deliver an OpenShift environment for development and testing purposes. Issues occurring during installation or usage of specific OpenShift applications are outside of the scope of CodeReady Containers and should be reported to the relevant project. For example, OpenShift issues are tracked on GitHub.

3.1. Basic troubleshooting

The majority of issues can be resolved by stopping a running CodeReady Containers virtual machine, deleting the virtual machine, and starting a new instance of the virtual machine.



To troubleshoot CodeReady Containers, perform the following steps:

  1. Stop the CodeReady Containers virtual machine:

    $ crc stop
  2. Delete the CodeReady Containers virtual machine:

    $ crc delete
  3. Start the CodeReady Containers virtual machine:

    $ crc start

    The cluster takes a minimum of four minutes to start the necessary containers and operators before serving a request.

If your issue has not been resolved by this procedure, perform the following steps:

  1. Search open issues for the issue that you are encountering.
  2. If no existing issue addresses the encountered issue, create an issue and attach the ~/.crc/crc.log file to the created issue. The ~/.crc/crc.log file contains detailed debugging and troubleshooting information which can help diagnose the problem that you are experiencing.

3.2. DNS configuration details

This section describes how CodeReady Containers configures networking. This can be useful for troubleshooting, or in case you are using a non-standard DNS setup, and want to adjust it for CodeReady Containers needs. The crc ip command can be used to obtain the VM IP address as needed. This address can change each time the VM is restarted.

3.2.1. Linux

  • CodeReady Containers expects NetworkManager to be used to manage networking.
  • NetworkManager is set up to use dnsmasq through the /etc/NetworkManager/conf.d/crc-nm-dnsmasq.conf configuration file.
  • The configuration file for this dnsmasq instance is /etc/NetworkManager/dnsmasq.d/crc.conf:
  • NetworkManager dnsmasq instance forwards requests for the crc.testing and apps-crc.testing domains to the DNS server which is a dnsmasq instance running inside the virtual machine.

3.2.2. macOS

  • CodeReady Containers creates a /etc/resolver/testing file which instructs macOS to forward all DNS requests for the testing domain to the CodeReady Containers virtual machine.
  • CodeReady Containers also adds an api.crc.testing entry to /etc/hosts pointing at the VM IP address. This is needed by the oc binary, see OpenShift issue #23266.

3.3. Troubleshooting expired certificates

Each released crc binary includes an embedded system bundle that expires 30 days after the release due to certificates embedded in the OpenShift cluster. Using an older crc binary or system bundle will result in an expired certificates error.


To resolve expired certificate errors:

  1. Download the latest CodeReady Containers release and place the crc binary in your $PATH.
  2. Remove the cluster with certificate errors using the crc delete command:

    $ crc delete

    The crc delete command will result in the loss of data stored in the CodeReady Containers virtual machine.

  3. Set up the new release:

    $ crc setup
  4. Start the new cluster:

    $ crc start