What causes "Clocks initialized, but clk_16k_vsys not active" in embassy-rs/embassy?

Enable `clk_16k_vsys` in the clock configuration passed to clock init before creating the RTC.

Clocks initialized, but clk_16k_vsys not active

Error message

Clocks initialized, but clk_16k_vsys not active

What it means

Clock configuration exists but the `clk_16k_vsys` entry is `Some(None)`: the 16 kHz clock on the VSYS power domain was not enabled during clock setup. The RTC runs from this clock and is not MRCC-gated, so the driver requires it explicitly and panics when it is absent.

Solutions

Enable `clk_16k_vsys` in the clock configuration passed to clock init before creating the RTC.
Verify the 16k oscillator (VSW/VSYS domain) is started, not just configured, per the MCXA reference manual.
If RTC is not actually needed, remove the Rtc::new call instead of enabling the clock.

Example fix

// before: ClockConfig { .. } // clk_16k_vsys not enabled
// after
let mut clocks = ClockConfig::default();
clocks.enable_clk_16k_vsys(); // or set in the clock init struct per BSP
embassy_mcxa::clocks::init(clocks);

Defensive patterns

Strategy: validation

Validate before calling

// In your ClockConfig, explicitly enable the 16k vsys clock before init:
let mut clocks = ClockConfig::default();
clocks.clk_16k_vsys = /* enabled per BSP API */;

Prevention

Always enable clk_16k_vsys in the clock config when using the RTC.
Don't disable low-power/16k clocks when RTC is used.
Test RTC bring-up right after changing clock configuration.

When it happens

Trigger: Calling `Rtc::new(...)` after clock init that did not enable the 16k vsys oscillator/clock (e.g. default clock config without `clk_16k_vsys` set, or it was disabled to save power).

Common situations: Using a clock config copied from a chip/example that doesn't enable the 16k VSYS clock; deliberately disabling low-power clocks for power reasons and then adding RTC; a board support package whose default clock config lacks this clock.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

AI-assisted analysis of embassy-rs/embassy@463a07b963 (2026-09-10). Data as JSON: /api/errors/725c573ac4ee005b. Report an issue: GitHub.

Appendix: source

Thrown at embassy-mcxa/src/rtc/mcxa2xx.rs:262

    _freq: u32,
    _wg: Option<WakeGuard>,
}

impl<'a> Rtc<'a> {
    /// Create a new instance of the real time clock.
    pub fn new<T: Instance>(
        _inst: Peri<'a, T>,
        _irq: impl crate::interrupt::typelevel::Binding<T::Interrupt, InterruptHandler<T>> + 'a,
        config: Config,
    ) -> Self {
        let info = T::info();

        // The RTC is NOT gated by the MRCC, but we DO need to make sure the 16k clock
        // on the vsys domain is active
        let clocks = with_clocks(|c| c.clk_16k_vsys.clone());
        let clk = match clocks {
            None => panic!("Clocks have not been initialized"),
            Some(None) => panic!("Clocks initialized, but clk_16k_vsys not active"),
            Some(Some(clk)) => clk,
        };

        let mut inst = Self {
            info,
            _inst: PhantomData,
            _freq: clk.frequency,
            _wg: WakeGuard::for_power(&clk.power),
        };

        inst.set_configuration(&config);

        // Enable RTC interrupt
        T::Interrupt::unpend();
        unsafe { T::Interrupt::enable() };

        inst
    }

View on GitHub (pinned to 463a07b963)