zeroclaw-labs/zeroclaw · error

tool linker

Error message

tool linker

What it means

Cached linker invariant in tool_linker: the once-built WASI plus tool-world Linker failed to register plugin imports. A deterministic wasmtime registration failure is treated as a bug via expect on the OnceLock initializer.

Solutions

  1. Ensure the plugin runtime's linker is initialized before instantiating plugin modules.
  2. Check plugin build/feature flags so the tool linker is available, and restart the runtime.
Defensive patterns

Strategy: fallback

When it happens

Trigger: Thrown at crates/zeroclaw-plugins/src/runtime.rs:55 when the library encounters an invalid state.

Common situations: See trigger scenarios.


AI-assisted analysis of zeroclaw-labs/zeroclaw@88bb9c8533 (2026-08-23). Data as JSON: /api/errors/d0dfcc324fca8da1. Report an issue: GitHub.

Appendix: source

Thrown at crates/zeroclaw-plugins/src/runtime.rs:55

    crate::component::add_wasi(&mut linker)?;
    let mut options = crate::component::bindings::tool::LinkOptions::default();
    options.plugins_wit_v0(true);
    wt(
        ToolPlugin::add_to_linker::<_, wasmtime::component::HasSelf<_>>(
            &mut linker,
            &options,
            |s| s,
        ),
        "failed to add tool plugin imports to linker",
    )?;
    Ok(linker)
}

/// Cached linker for plugins without `HttpClient`: base WASI plus the tool
/// world, no network.
fn tool_linker() -> &'static Linker<PluginState> {
    static LINKER: OnceLock<Linker<PluginState>> = OnceLock::new();
    LINKER.get_or_init(|| base_linker().expect("tool linker"))
}

/// Cached linker for `HttpClient` plugins: the base surface plus `wasi:http`.
/// Built only once, on first use by an HTTP-granted plugin.
fn tool_linker_http() -> &'static Linker<PluginState> {
    static LINKER: OnceLock<Linker<PluginState>> = OnceLock::new();
    LINKER.get_or_init(|| {
        let mut linker = base_linker().expect("tool linker");
        crate::component::add_wasi_http(&mut linker).expect("tool http linker");
        linker
    })
}

/// Compile and instantiate a tool plugin under one host-issued scope.
///
/// The scope decides whether the store carries an outbound-HTTP context and
/// whether the linker exposes `wasi:http`; deriving both from the same scope
/// prevents authority from drifting between instantiation and execution.

View on GitHub (pinned to 88bb9c8533)