{"record":{"id":"ce687c0069990739","repo":"Pumpkin-MC/Pumpkin","slug":"plugin-was-built-for-an-incompatible-api-version","errorCode":null,"errorMessage":"Plugin was built for an incompatible API version. Please rebuild it against this Pumpkin build.","messagePattern":"Plugin was built for an incompatible API version\\. Please rebuild it against this Pumpkin build\\.","errorType":"error_code","errorClass":"LoaderError","httpStatus":null,"severity":"error","filePath":"crates/pumpkin/src/plugin/loader/mod.rs","lineNumber":57,"sourceCode":"    #[error(\"Failed to load library: {0}\")]\n    LibraryLoad(String),\n\n    #[error(\"Missing plugin metadata\")]\n    MetadataMissing,\n\n    #[error(\"Missing plugin entrypoint\")]\n    EntrypointMissing,\n\n    #[error(\"Plugin initialization failed: {0}\")]\n    InitializationFailed(String),\n\n    #[error(\"Runtime error: {0}\")]\n    RuntimeError(String),\n\n    #[error(\"Invalid loader data\")]\n    InvalidLoaderData,\n\n    #[error(\n        \"Plugin was built for an incompatible API version. Please rebuild it against this Pumpkin build.\"\n    )]\n    ApiVersionMissing,\n\n    #[error(\n        \"Plugin API version mismatch (plugin {plugin_version}, server {server_version}). Please rebuild it against this Pumpkin build.\"\n    )]\n    ApiVersionMismatch {\n        plugin_version: u32,\n        server_version: u32,\n    },\n\n    #[error(\"Wasm plugin initialization error: {0}\")]\n    WasmInitializationError(#[from] PluginInitError),\n}\n","sourceCodeStart":39,"sourceCodeEnd":73,"githubUrl":"https://github.com/Pumpkin-MC/Pumpkin/blob/8d4639e25a57c15e47448ec327c780d41bbf2356/crates/pumpkin/src/plugin/loader/mod.rs#L39-L73","documentation":"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.","triggerScenarios":"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`.","commonSituations":"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.","solutions":["Rebuild the plugin against the current Pumpkin / pumpkin-plugin crate version and redeploy the new .wasm","Update the plugin SDK dependency (cargo update -p pumpkin-plugin) in the plugin project so it embeds the API version","Download a release of the plugin built for your exact Pumpkin server version","If you author the plugin manually, add the required API version export to the component"],"exampleFix":"// plugin Cargo.toml (before)\npumpkin-plugin = \"0.1\"\n// after — match your server build\npumpkin-plugin = \"=0.2.1\" # then `cargo build --target wasm32-wasip2` and redeploy","handlingStrategy":"validation","validationCode":"// before loading a plugin, ensure it exports an API version\nfn has_api_version(bytes: &[u8]) -> bool {\n    // require the component to declare a version export; Pumpkin rejects absent versions\n    !bytes.is_empty() && plugin_exports_version(bytes)\n}","typeGuard":"fn plugin_exports_version(bytes: &[u8]) -> bool { /* inspect component exports via wasm-tools */ }","tryCatchPattern":"match loader.load(path) {\n    Err(PluginLoadError::ApiVersionMissing) => log(\"rebuild plugin against this Pumpkin build\"),\n    other => other,\n}","preventionTips":["Always build plugins with a pumpkin-plugin SDK version that embeds the API version","Track Pumpkin release notes and rebuild all plugins on server upgrades","Only distribute plugins from builds matching your server version"],"tags":["plugin","wasm","api-version","loader"],"backgroundTag":"incompatible-source-type","analyzedSha":"8d4639e25a57c15e47448ec327c780d41bbf2356","analyzedAt":"2026-09-09T15:32:22.916Z","contentChangedAt":"2026-09-09T15:32:22.916Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}