Troubleshooting

Procedure

• Run the following command to check the version information:

  $ microshift version

  Copy to Clipboard Toggle word wrap

  Example output

  MicroShift Version: 4.16-0.microshift-e6980e25
  Base OCP Version: 4.16

  Copy to Clipboard Toggle word wrap

Procedure

• To get the version number using the OpenShift CLI (oc), view the kube-public/microshift-version config map by running the following command:

  $ oc get configmap -n kube-public microshift-version -o yaml

  Copy to Clipboard Toggle word wrap

  Example output

  apiVersion: v1
  data:
    major: "4"
    minor: "20"
    version: 4.20.0-0.microshift-fa441af87431
  kind: ConfigMap
  metadata:
    creationTimestamp: "2025-11-03T21:06:11Z"
    name: microshift-version
    namespace: kube-public

  Copy to Clipboard Toggle word wrap

Procedure

• To display the base database version information, run the following command:

  $ microshift-etcd version

  Copy to Clipboard Toggle word wrap

  Example output

  microshift-etcd Version: 4.16.0
  Base etcd Version: 3.5.13

  Copy to Clipboard Toggle word wrap

• To display the full database version information, run the following command:

  $ microshift-etcd version -o json

  Copy to Clipboard Toggle word wrap

  Example output

  {
    "major": "4",
    "minor": "16",
    "gitVersion": "4.16.0~rc.1",
    "gitCommit": "140777711962eb4e0b765c39dfd325fb0abb3622",
    "gitTreeState": "clean",
    "buildDate": "2025-11-03T16:37:53Z",
    "goVersion": "go1.21.9"
    "compiler": "gc",
    "platform": "linux/amd64",
    "patch": "",
    "etcdVersion": "3.5.13"
  }

  Copy to Clipboard Toggle word wrap

Procedure

• Check the system status, which returns the node status, by running the following command:

  $ sudo systemctl status microshift

  Copy to Clipboard Toggle word wrap

  If MicroShift fails to start, this command returns the logs from the previous run.

  Example healthy output

  ● microshift.service - MicroShift
       Loaded: loaded (/usr/lib/systemd/system/microshift.service; enabled; preset: disabled)
       Active: active (running) since <day> <date> 12:39:06 UTC; 47min ago
     Main PID: 20926 (microshift)
        Tasks: 14 (limit: 48063)
       Memory: 542.9M
          CPU: 2min 41.185s
       CGroup: /system.slice/microshift.service
               └─20926 microshift run
  
  <Month-Day> 13:23:06 i-06166fbb376f14a8b.<hostname> microshift[20926]: kube-apiserver I0528 13:23:06.876001   20926 controll>
  <Month-Day> 13:23:06 i-06166fbb376f14a8b.<hostname> microshift[20926]: kube-apiserver I0528 13:23:06.876574   20926 controll>
  # ...

  Copy to Clipboard Toggle word wrap

• Optional: Get comprehensive logs by running the following command:

  $ sudo journalctl -u microshift

  Copy to Clipboard Toggle word wrap
  Note

  The default configuration of the systemd journal service stores data in a volatile directory. To persist system logs across system starts and restarts, enable log persistence and set limits on the maximum journal data size.

• Optional: If MicroShift is running, check the status of active pods by entering the following command:

  $ oc get pods -A

  Copy to Clipboard Toggle word wrap

  Example output

  NAMESPACE                   NAME                                                     READY   STATUS   RESTARTS  AGE
  default                     i-06166fbb376f14a8bus-west-2computeinternal-debug-qtwcr  1/1     Running  0		    46m
  kube-system                 csi-snapshot-controller-5c6586d546-lprv4                 1/1     Running  0		    51m
  kube-system                 csi-snapshot-webhook-6bf8ddc7f5-kz6k9                    1/1     Running  0		    51m
  openshift-dns               dns-default-45jl7                                        2/2     Running  0		    50m
  openshift-dns               node-resolver-7wmzf                                      1/1     Running  0		    51m
  openshift-ingress           router-default-78b86fbf9d-qvj9s                          1/1     Running  0		    51m
  openshift-ovn-kubernetes    ovnkube-master-5rfhh                                     4/4     Running  0		    51m
  openshift-ovn-kubernetes    ovnkube-node-gcnt6                                       1/1     Running  0		    51m
  openshift-service-ca        service-ca-bf5b7c9f8-pn6rk                               1/1     Running  0		    51m
  openshift-storage           topolvm-controller-549f7fbdd5-7vrmv                      5/5     Running  0		    51m
  openshift-storage           topolvm-node-rht2m                                       3/3     Running  0		    50m

  Copy to Clipboard Toggle word wrap

  Note

  This example output shows a basic MicroShift installation. If you installed optional RPMs, the status of pods running those services is also expected in your output.

Prerequisites

• You must have the sos package installed.
• You have root access to the host.

• Not waiting several minutes after a system start to successfully stop MicroShift. The system must complete health checks and any other background processes before a back up can succeed.

• If MicroShift stopped running because of an error, you cannot perform a backup of the data.

  • Make sure the system is healthy.
  • Stop it in a healthy state before attempting a backup.
• If you do not have enough storage for the data, the backup fails. Ensure that you have enough storage for MicroShift data.
• If you do not have the required user permissions, a backup can fail. Ensure that you have the correct user permissions to create a backup and perform the required configurations.

• Logs print to the terminal console during manual backups.
• Logs are automatically generated for rpm-ostree system automated backups as part of the MicroShift journal logs.

Procedure

• Check the logs by running the following command:

  $ sudo journalctl -u microshift

  Copy to Clipboard Toggle word wrap

• If a storage migration fails, there is usually an unresolvable discrepancy between versions that requires manual review.

Procedure

• Get comprehensive MicroShift journal logs by running the following command:

  $ sudo journalctl -u microshift

  Copy to Clipboard Toggle word wrap

• Check the greenboot journal logs by running the following command:

  $ sudo journalctl -u greenboot-healthcheck

  Copy to Clipboard Toggle word wrap

• Examining the comprehensive logs of a specific boot uses three steps. First list the boots, then select the one you want from the list you obtained:

  • List the boots present in the journal logs by running the following command:

    $ sudo journalctl --list-boots

    Copy to Clipboard Toggle word wrap

    Example output

    IDX  BOOT ID                          	FIRST ENTRY                 LAST ENTRY
     0   681ece6f5c3047e183e9d43268c5527f 	<Day> <Date> 12:27:58 UTC 	<Day> <Date>> 13:39:41 UTC
    #....

    Copy to Clipboard Toggle word wrap

  • Check the journal logs for the specific boot you want by running the following command:

    $ sudo journalctl --boot <my_boot_ID> 

    1

    Copy to Clipboard Toggle word wrap

    1

    Replace <my-boot-ID> with the number assigned to the specific boot that you want to check.

  • Check the journal logs for the boot of a specific service by running the following command:

    $ sudo journalctl --boot <my_boot_ID> -u <service_name> 

    1

    2

    Copy to Clipboard Toggle word wrap

    1

    Replace <my-boot-ID> with the number assigned to the specific boot that you want to check.

    2

    Replace <service_name> with the name of the service that you want to check.

Procedure

• To see a report of health check status, use the following command:

  $ systemctl show --property=SubState --value greenboot-healthcheck.service

  Copy to Clipboard Toggle word wrap
  • An output of start means that greenboot checks are still running.
  • An output of exited means that checks have passed and greenboot has exited. Greenboot runs the scripts in the green.d directory when the system is a healthy state.
  • An output of failed means that checks have not passed. Greenboot runs the scripts in red.d directory when the system is in this state and might restart the system.

• To see a report showing the numerical exit code of the service where 0 means success and non-zero values mean a failure occurred, use the following command:

  $ systemctl show --property=ExecMainStatus --value greenboot-healthcheck.service

  Copy to Clipboard Toggle word wrap

• To see a report showing a message about boot status, such as Boot Status is GREEN - Health Check SUCCESS, use the following command:

  $ cat /run/motd.d/boot-status

  Copy to Clipboard Toggle word wrap

Prerequisites

• You have installed jq.
• You have root access to the node.

Procedure

• Edit the /etc/microshift/config.yaml file to set the memoryLimitMB value.

  etcd:
    memoryLimitMB: 128

  Copy to Clipboard Toggle word wrap
  Note

  The minimum required value for memoryLimitMB on MicroShift is 128 MB. Values close to the minimum value are more likely to impact etcd performance. The lower the limit, the longer etcd takes to respond to queries. If the limit is too low or the etcd usage is high, queries time out.