What causes "Clocks have not been initialized" in embassy-rs/embassy?

Initialize clocks before creating the RTC (call the chip's clock init, e.g. `embassy_mcxa::clocks::init(...)` / `init_clocks`, as first step of main).

embassy-rs/embassy · critical

Clocks have not been initialized

Error message

Clocks have not been initialized

What it means

The RTC driver needs the 16 kHz VSYS-domain clock to be registered with the embassy clock manager before `Rtc::new()` runs. `with_clocks` returns `None` when no clock configuration exists at all, meaning `clock_init`/clock setup was never called, so the driver panics rather than running against unknown timing.

Solutions

Initialize clocks before creating the RTC (call the chip's clock init, e.g. `embassy_mcxa::clocks::init(...)` / `init_clocks`, as first step of main).
Ensure the clock config enables the 16k vsys clock (clk_16k_vsys) or you will hit the next panic ('clk_16k_vsys not active') instead.
Compare startup order with the board's embassy example (rtc example) to confirm init sequence.

Example fix

// before
fn main() {
    let rtc = Rtc::new(p.RTC, Default::default()); // panics: clocks not initialized
}
// after
fn main() {
    embassy_mcxa::clocks::init(&config.clocks /* with clk_16k_vsys enabled */);
    let rtc = Rtc::new(p.RTC, Default::default());
}

Defensive patterns

Strategy: validation

Validate before calling

// Ensure clock init runs before any peripheral construction:
embassy_mcxa::clocks::init(clock_config); // first line of main
let rtc = Rtc::new(p.RTC, Default::default()); // after init

Prevention

Follow the board example's startup order: clocks first, then peripherals.
Never construct drivers before embassy clock init in main.
Add a comment/comment-check that RTC depends on clk_16k_vsys.

When it happens

Trigger: Constructing `Rtc::new(...)` before any clock initialization (no `embassy-mcxa::clocks::init`/`init_clocks` call, or it runs after RTC creation), e.g. calling RTC::new at the very top of main.

Common situations: Adding an RTC driver to an existing project whose clock setup was copied from a different chip variant; reordering main so RTC::new precedes clock init; forgetting clocks entirely in a minimal test program.

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/532bcf986932856c. Report an issue: GitHub.

Appendix: source

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

    info: &'static Info,
    _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)