Troubleshooting CRC

The goal of CRC is to deliver an OpenShift Container Platform environment for development and testing purposes. Issues occurring during installation or usage of specific OpenShift applications are outside of the scope of CRC. Report such issues to the relevant project.

Getting shell access to the OpenShift cluster

To access the cluster for troubleshooting or debugging purposes, follow this procedure.

Direct access to the OpenShift Container Platform cluster is not needed for regular use and is strongly discouraged.

Prerequisites

Enable OpenShift CLI (oc) access to the cluster and log in as the kubeadmin user. For detailed steps, see Accessing the OpenShift cluster with the OpenShift CLI.

Procedure

Run the oc get nodes command to identify the desired node. The output will be similar to this:

$ oc get nodes
NAME                 STATUS   ROLES           AGE    VERSION
crc-shdl4-master-0   Ready    master,worker   7d7h   v1.14.6+7e13ab9a7

Run oc debug nodes/<node> where <node> is the name of the node printed in the previous step.

Troubleshooting expired certificates

The system bundle of OpenShift Container Platform in each released crc executable expires 1 year after the release. This expiration is due to certificates embedded in the OpenShift Container Platform cluster. The crc start command triggers an automatic certificate renewal process when needed. Certificate renewal can add up to five minutes to the start time of the cluster.

To avoid this additional startup time, or in case of failures in the certificate renewal process, use the following procedure:

Procedure

To resolve expired certificate errors that cannot be automatically renewed:

Download the latest CRC release and place the crc executable in your $PATH.
Save any desired information stored in your existing instance.
Delete the existing CRC instance.
```
$ crc delete
```
Set up the new release:
```
$ crc setup
```
Start the new instance:
```
$ crc start
```

Troubleshooting bundle version mismatch

Created CRC instances contain bundle information and instance data. Bundle information and instance data is not updated when setting up a new CRC release. This information is not updated due to customization in the earlier instance data. This will lead to errors when running the crc start command:

$ crc start
...
FATA Bundle 'crc_hyperkit_4.2.8.crcbundle' was requested, but the existing VM is using
'crc_hyperkit_4.2.2.crcbundle'

Procedure

Save any desired information stored in your existing instance.
Delete the existing CRC instance.
```
$ crc delete
```
Start a new CRC instance:
```
$ crc start
```

Troubleshooting unknown issues

Resolve most issues by restarting CRC with a clean state. This involves stopping the instance, deleting it, reverting changes made by the crc setup command, reapplying those changes, and restarting the instance.

Prerequisites

You have set up CRC.
You have started the CRC instance.
You are using the latest CRC release. Using a version earlier than CRC 1.2.0 might result in errors related to expired x509 certificates. For more information, see Troubleshooting expired certificates.

Procedure

To troubleshoot CRC, perform the following steps:

Stop the CRC instance:
```
$ crc stop
```
Save any desired information stored in your existing instance.
Delete the existing CRC instance.
```
$ crc delete
```
Clean up remaining changes from the crc setup command:
```
$ crc cleanup
```
The crc cleanup command removes an existing CRC instance and reverts changes to DNS entries created by the crc setup command.
Set up your host machine to reapply the changes:
```
$ crc setup
```
Start the CRC instance:
```
$ crc start
```
The cluster takes a minimum of four minutes to start the necessary containers and Operators before serving a request.

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

Search open issues for the issue that you are encountering.
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 has detailed debugging and troubleshooting information which can help diagnose the problem that you are experiencing. In case you’re looking for more detailed information about virtual machine startup, state transitions and errors you can look into serial console logs created by virtual machine hypervisors. Here are the locations where you can find these logs:
libvirt

Find the log file in /var/log/libvirt/qemu/crc.log

vfkit

Find the log file in ~/.crc/vfkit.log

hyper-v
Event Logs for Hyper-V

Go to start and open Event Viewer.

Navigate to Applications and Services Logs → Microsoft → Windows.

Click Hyper-V-VMMS to view Hyper-V Virtual Machine Management logs.

Click Hyper-V-Worker to view Hyper-V Worker logs.

VM Configuration Logs

Open the Hyper-V configuration directory. By default, it’s located at : C:\ProgramData\Microsoft\Windows\Hyper-V.

In this directory, open your virtual machine log file, such as <virtual_machine_name>.evtx), that records the events related to your virtual machine.