What causes "failed to find worker context" in yewstack/yew?

Wrap the consuming component's subtree in > so the provider is an ancestor: html! { path={AttrValue::from("/agent.js")}> > }

yewstack/yew · critical

failed to find worker context

Error message

failed to find worker context

What it means

use_oneshot_runner<T> (packages/yew-agent/src/oneshot/hooks.rs:51) fetches an OneshotProviderState<T> from Yew's context system and panics with .expect when it is absent. The context only exists if an ancestor component rendered <OneshotProvider<T>> (packages/yew-agent/src/oneshot/provider.rs:90), so the panic means the hook ran in a subtree with no matching provider for that agent type T.

Source

Thrown at packages/yew-agent/src/oneshot/hooks.rs:51

    }
}

impl<T> PartialEq for UseOneshotRunnerHandle<T>
where
    T: Oneshot,
{
    fn eq(&self, rhs: &Self) -> bool {
        self.state == rhs.state
    }
}

/// A hook to create a runner to an oneshot agent.
#[hook]
pub fn use_oneshot_runner<T>() -> UseOneshotRunnerHandle<T>
where
    T: Oneshot + 'static,
{
    let state = use_context::<OneshotProviderState<T>>().expect("failed to find worker context");

    UseOneshotRunnerHandle { state }
}

View on GitHub (pinned to 0e4a05472f)

Solutions

Wrap the consuming component's subtree in <OneshotProvider<MyAgent>> so the provider is an ancestor: html! { <OneshotProvider<MyAgent, Bincode> path={AttrValue::from("/agent.js")}> <Page /> </OneshotProvider<MyAgent, Bincode>> }
Verify the generic agent type passed to use_oneshot_runner is exactly the type given to OneshotProvider
If the provider is conditionally rendered, ensure it mounts before any child calls the hook (render the provider unconditionally at the app root)

Example fix

// before
html! { <Page /> }  // Page calls use_oneshot_runner::<MyAgent>()

// after
html! {
    <OneshotProvider<MyAgent, Bincode> path={AttrValue::from("/agent.js")}>
        <Page />
    </OneshotProvider<MyAgent, Bincode>>
}

Defensive patterns

Strategy: validation

Validate before calling

// ensure the provider is an ancestor of every use_oneshot_runner call site
// html! { <OneshotProvider<MyAgent, Bincode> path={AttrValue::from("/agent.js")}>
//     <ConsumingComponent />
// </OneshotProvider<MyAgent, Bincode>> }

Type guard

// debug-only guard: place at the top of the consuming component
// #[cfg(debug_assertions)]
// fn assert_provider<T: 'static>() { yew::functional::use_context::<yew_agent::oneshot::OneshotProviderState<T>>().expect("missing OneshotProvider<T> ancestor"); }

Prevention

Mount OneshotProvider at the app root so no route can bypass it
Keep the agent type parameter identical between provider and hook
Wrap components in the provider in tests too — the hook panics outside the provider subtree

When it happens

Trigger: Calling use_oneshot_runner::<MyAgent>() inside a component whose ancestors never rendered <OneshotProvider<MyAgent>>; placing the provider as a sibling instead of an ancestor; registering the provider for a different agent type T than the one requested by the hook.

Common situations: Adding an oneshot agent hook to a deep page component while the provider was only added on another branch of the tree; forgetting to re-add the provider after refactoring the root layout; generic parameter mismatch so the context type does not line up.

Related errors

AI-assisted analysis of yewstack/yew@0e4a05472f (2026-08-22). Data as JSON: /api/errors/82cb2b71850a69de. Report an issue: GitHub.