Pumpkin-MC/Pumpkin · error · PluginInitError

Failed to instantiate plugin

Error message

Failed to instantiate plugin: {0}

What it means

This thiserror variant `InstantiationFailed` wraps a wasmtime::Error raised while instantiating a WASM plugin component in the Pumpkin plugin loader. Wasmtime failed to create a running instance of the compiled component (linking imports, memory, or start execution). The plugin file itself loaded but could not be turned into a live instance.

Solutions

1. Rebuild the plugin against the same WIT world / pumpkin-api version as the server
2. Check that the wasmtime runtime version on the server matches the one the plugin was compiled with
3. Validate the component with `wasmtime compile` or `wasm-tools validate` before deploying
4. Read the wrapped wasmtime::Error in the log for the exact missing import

// before loading
if !std::path::Path::new(&plugin_path).exists() { return Err("plugin file missing"); }
// optionally: wasm-tools validate plugin.wasm

fn is_wasmtime_error(e: &PluginError) -> Option<&wasmtime::Error> { if let PluginError::InstantiationFailed(e) = e { Some(e) } else { None } }

match loader.load(path) { Err(PluginError::InstantiationFailed(e)) => { log::error!("plugin instantiation failed: {e}"); /* skip plugin */ }, r => r? }

When it happens

Trigger: Loading a .wasm plugin whose component imports functions/types the host does not provide (mismatched WIT world version), or a component with a failing start/instantiation section.

Common situations: Plugin built against a different pumpkin-plugin API version than the server; missing host exports after a server update; corrupted or partially downloaded wasm file.

Related errors

• Calling `init_plugin` failed
• Wasm plugin initialization error
• Engine creation failed
• Failed to setup linker
• Plugin is built against a different API version

AI-assisted analysis of Pumpkin-MC/Pumpkin@8d4639e25a (2026-09-09). Data as JSON: /api/errors/44167e4a4add2b12. Report an issue: GitHub.

Appendix: source

Thrown at crates/pumpkin/src/plugin/loader/wasm/wasm_host/mod.rs:37

pub mod wit;

#[derive(Error, Debug)]
pub enum PluginInitError {
    #[error("Engine creation failed: {0}")]
    EngineCreationFailed(wasmtime::Error),
    #[error("Failed to setup linker: {0}")]
    LinkerSetupFailed(wasmtime::Error),
    #[error("Plugin is built against a different API version: {0}")]
    ApiVersionMismatch(wasmtime::Error),
    #[error("Failed to read plugin file: {0}")]
    FileReadFailed(std::io::Error),
    #[error("Failed to load plugin as component: {0}")]
    ComponentNewFailed(wasmtime::Error),
    #[error("Failed to create cache data for plugin: {0}")]
    ComponentCacheSerializeFailed(wasmtime::Error),
    #[error("Failed to write cache file for plugin: {0}")]
    ComponentCacheWriteFailed(std::io::Error),
    #[error("Failed to instantiate plugin: {0}")]
    InstantiationFailed(wasmtime::Error),
    #[error("Calling `init_plugin` failed: {0}")]
    CallInitPluginFailed(wasmtime::Error),
    #[error("Calling `get_metadata` failed: {0}")]
    CallGetMetadataFailed(wasmtime::Error),
    #[error("Failed to get absolute path: {0}")]
    PathResolutionFailed(std::io::Error),
    #[error("Failed to create cache: {0}")]
    CacheCreationFailed(wasmtime::Error),
}

#[derive(Clone, Copy, Default)]
struct SocketPolicy {
    tcp_connect: bool,
    tcp_bind: bool,
    udp_send: bool,
    udp_receive: bool,
    udp_bind: bool,

View on GitHub (pinned to 8d4639e25a)