Pumpkin-MC/Pumpkin · error · PluginInitError

Plugin is built against a different API version

Error message

Plugin is built against a different API version: {0}

What it means

This is `PluginInitError::ApiVersionMismatch`, wrapping a `wasmtime::Error`. During plugin loading, Pumpkin calls a guest export to read the plugin's API version and that call failed, so the plugin is assumed to be built against a different API and is rejected. Unlike the loader-level version errors, this one fires when the version check itself faults at the WASM boundary.

Solutions

  1. Rebuild the plugin against the current Pumpkin API and WIT world
  2. Confirm the file is a WASM component built with wasm32-wasip2, not a bare module
  3. Check the wrapped wasmtime::Error for the exact trap/missing export
  4. Use a plugin build matching your server release

Example fix

// before: cargo build --target wasm32-wasi
// after:  cargo build --target wasm32-wasip2 # produce a proper component
Defensive patterns

Strategy: validation

Validate before calling

// pre-validate the artifact is a component for this API
if !wasm_tools::is_component(&bytes) { return Err("plugin must be a wasm32-wasip2 component"); }

Type guard

fn is_valid_plugin_component(bytes: &[u8]) -> bool { bytes.starts_with(&[0x0d, 0x00, 0x01, 0x00]) /* component preamble */ }

Try / catch

match init.load_component(&bytes) {
    Err(PluginInitError::ApiVersionMismatch(e)) => eprintln!("plugin built against a different API: {e} — rebuild"),
    other => other,
}

Prevention

When it happens

Trigger: Invoking the plugin's version/instance export via wasmtime during load and the trap/error indicates a foreign or incompatible component (missing export, wrong signature, version check trap).

Common situations: Loading a core-module (not a component) .wasm file, a plugin compiled for a different WIT world, or a plugin whose version export traps.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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

Appendix: source

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

    Context, PluginMetadata, cache::calculate_hash_for_bytes,
    loader::wasm::wasm_host::state::PluginHostState, permissions,
};
use pumpkin_plugin_runtime::RuntimeSpawner;

pub mod args;
pub mod concurrent_store;
pub mod logging;
pub mod signature;
pub mod state;
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}")]

View on GitHub (pinned to 8d4639e25a)