Pumpkin-MC/Pumpkin · error · LoaderError

Plugin was built for an incompatible API version. Please…

Error message

Plugin was built for an incompatible API version. Please rebuild it against this Pumpkin build.

What it means

This is `PluginLoadError::ApiVersionMissing` from Pumpkin's plugin loader. It means the plugin's WASM component does not export an API version at all, so the server cannot verify compatibility and refuses to load it. Pumpkin requires every plugin to declare the API version it was built against; without it the plugin may call incompatible host interfaces.

Solutions

1. Rebuild the plugin against the current Pumpkin / pumpkin-plugin crate version and redeploy the new .wasm
2. Update the plugin SDK dependency (cargo update -p pumpkin-plugin) in the plugin project so it embeds the API version
3. Download a release of the plugin built for your exact Pumpkin server version
4. If you author the plugin manually, add the required API version export to the component

Example fix

// plugin Cargo.toml (before)
pumpkin-plugin = "0.1"
// after — match your server build
pumpkin-plugin = "=0.2.1" # then `cargo build --target wasm32-wasip2` and redeploy

// before loading a plugin, ensure it exports an API version
fn has_api_version(bytes: &[u8]) -> bool {
    // require the component to declare a version export; Pumpkin rejects absent versions
    !bytes.is_empty() && plugin_exports_version(bytes)
}

fn plugin_exports_version(bytes: &[u8]) -> bool { /* inspect component exports via wasm-tools */ }

match loader.load(path) {
    Err(PluginLoadError::ApiVersionMissing) => log("rebuild plugin against this Pumpkin build"),
    other => other,
}

When it happens

Trigger: Loading a `.wasm` plugin whose metadata/version export is missing — typically a plugin built for an older or pre-versioning Pumpkin API, or a hand-rolled component that never exported the version field checked during `get_metadata`.

Common situations: Upgrading the server to a newer Pumpkin build without recompiling old plugins; downloading a plugin compiled against a much older API; building a plugin with an outdated pumpkin-plugin SDK that didn't embed a version.

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

• Plugin API version mismatch
• Plugin is built against a different API version
• Failed to load library
• Missing plugin metadata
• Missing plugin entrypoint

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

Appendix: source

Thrown at crates/pumpkin/src/plugin/loader/mod.rs:57

    #[error("Failed to load library: {0}")]
    LibraryLoad(String),

    #[error("Missing plugin metadata")]
    MetadataMissing,

    #[error("Missing plugin entrypoint")]
    EntrypointMissing,

    #[error("Plugin initialization failed: {0}")]
    InitializationFailed(String),

    #[error("Runtime error: {0}")]
    RuntimeError(String),

    #[error("Invalid loader data")]
    InvalidLoaderData,

    #[error(
        "Plugin was built for an incompatible API version. Please rebuild it against this Pumpkin build."
    )]
    ApiVersionMissing,

    #[error(
        "Plugin API version mismatch (plugin {plugin_version}, server {server_version}). Please rebuild it against this Pumpkin build."
    )]
    ApiVersionMismatch {
        plugin_version: u32,
        server_version: u32,
    },

    #[error("Wasm plugin initialization error: {0}")]
    WasmInitializationError(#[from] PluginInitError),
}

View on GitHub (pinned to 8d4639e25a)