Troubleshoot device onboarding

Diagnose common first-boot onboarding failures, inspect service logs, and re-enter onboarding mode when you must repeat the wizard on a device.

About this task

Common symptoms

Symptom Likely cause

Temporary wizard WiFi network (name starts with flightctl-) is not visible

Wireless interface unavailable, provisioning WiFi is disabled in image configuration, or hostapd/dnsmasq packages are not installed.

Browser cannot reach Cockpit on port 9090

Setup network not configured, wrong interface selected, or firewall blocking access.

Network apply step fails

Invalid static IP, missing carrier on ethernet port, duplicate address on the network, or invalid VLAN settings. The onboarding service rolls back temporary flightctl-onboarding- NetworkManager profiles and saves failure logs for review.

Device does not appear in the device inventory after configuration

Production interface cannot reach the Red Hat Edge Manager endpoint, enrollment was not approved, or enrollment credentials are missing or invalid. See Enrolling devices in the Additional resources section.

Procedure

  1. Verify that onboarding is still active: 
    systemctl status flightctl-onboarding-setup.service
ls /var/lib/flightctl-onboarding/.onboarding-complete

    When the marker file exists, onboarding has already completed and the wizard is no longer available.

  2. Inspect onboarding service logs: 
    journalctl -u flightctl-onboarding-setup.service
journalctl -u flightctl-onboarding-dnsmasq@*.service
journalctl -u flightctl-onboarding-captive-portal@*.service
journalctl -u flightctl-onboarding-mask-greenboot.service
journalctl -u flightctl-agent.service
  3. When WiFi access is unavailable, confirm that the required packages are installed or use a wired or local-console access method. See Access the onboarding wizard.
  4. When network configuration fails, inspect the saved failure logs and reconnect to the wizard by using a supported access method. Correct the interface, IP address, gateway, DNS, VLAN, or enrollment settings.

    Re-entering onboarding mode

    To run the wizard again on a device that already completed onboarding:

  5. Remove the completion marker: 
    rm -f /var/lib/flightctl-onboarding/.onboarding-complete
  6. Re-enable and start the onboarding service: 
    systemctl enable flightctl-onboarding-setup.service
systemctl start flightctl-onboarding-setup.service
    Warning

    Re-entering onboarding mode is intended for lab recovery and field troubleshooting. Removing the marker on a managed production device can interrupt agent operation until onboarding completes again.

    Additional resources