Pumpkin-MC/Pumpkin · error · LoaderError

Plugin API version mismatch

Error message

Plugin API version mismatch (plugin {plugin_version}, server {server_version}). Please rebuild it against this Pumpkin build.

What it means

This is `PluginLoadError::ApiVersionMismatch { plugin_version, server_version }`. The plugin DID export an API version, but the number does not equal the server's API version, so Pumpkin refuses to load it to avoid ABI/interface incompatibilities. The message interpolates both versions so you can see which side is stale.

Solutions

  1. Compare the reported plugin_version vs server_version and rebuild the plugin against the server's API version
  2. Or update the Pumpkin server to a build matching the plugin's API version
  3. Pin plugin and server to the same release train in CI so they are always built together
  4. Check the plugin's release notes for a build matching your server version

Example fix

// server reports: plugin 3, server 4
// before: plugin built with pumpkin-plugin 0.2 (api 3)
// after: bump and rebuild
// Cargo.toml: pumpkin-plugin = "=0.3.0" # api 4, matching server
Defensive patterns

Strategy: validation

Validate before calling

// check plugin version metadata before load
assert_eq!(plugin.api_version, server.api_version, "rebuild plugin for api {}", server.api_version);

Type guard

fn versions_match(p: &PluginMetadata, s: &ServerInfo) -> bool { p.api_version == s.api_version }

Try / catch

match loader.load(path) {
    Err(PluginLoadError::ApiVersionMismatch { plugin_version, server_version }) => {
        eprintln!("plugin api {plugin_version} != server api {server_version}; rebuild plugin");
    }
    other => other,
}

Prevention

When it happens

Trigger: Calling the plugin loader with a `.wasm` component whose exported plugin API version differs from the running server's `PLUGIN_API_VERSION` — checked during metadata loading in `crates/pumpkin/src/plugin/loader/mod.rs`.

Common situations: Server updated to a new Pumpkin build while the plugin binary is from an older release; plugin built with a newer SDK than the pinned server; mixed plugin repo versions after a version bump PR.

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/a3f5e172bd97def3. Report an issue: GitHub.

Appendix: source

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

    #[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)