Pumpkin-MC/Pumpkin · error · LoaderError

Failed to load library

Error message

Failed to load library: {0}

What it means

This is LoaderError::LibraryLoad(String), thrown by the Pumpkin plugin loader's unified error type. It means the plugin's dynamic library (.so/.dylib/.dll) could not be loaded into the process. The underlying OS/loader error is carried in the String payload.

Solutions

1. Check the error string payload for the underlying OS error (e.g. missing dependency, bad ELF header)
2. Confirm the plugin file exists at the configured path and matches the platform/architecture
3. Rebuild the plugin against the current Pumpkin version
4. Run ldd (Linux) on the plugin to find missing shared library dependencies

Example fix

null

// before enabling: check the plugin file exists
if !plugin_path.exists() {
    bail!("plugin library not found at {}", plugin_path.display());
}

null

match loader.load(path) {
    Err(LoaderError::LibraryLoad(msg)) => eprintln!("plugin .so failed to load: {msg}"),
    Ok(p) => enable(p),
    Err(e) => return Err(e),
}

When it happens

Trigger: Raised when the plugin loader calls the dynamic library loading routine and it fails: missing file, invalid shared object, unresolved symbols, or incompatible ABI.

Common situations: Plugin path is wrong or the .so file is missing; plugin compiled for a different architecture or libc; missing transitive shared library dependencies; plugin built against a different Pumpkin API.

Related errors

• Missing plugin entrypoint
• Missing plugin metadata
• Plugin initialization failed
• Runtime error
• Invalid loader data

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

Appendix: source

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

    Pin<Box<dyn Future<Output = Result<(), LoaderError>> + Send + 'a>>;

pub trait PluginLoader: Send + Sync {
    /// Load a plugin from the specified path
    fn load<'a>(&'a self, path: &'a Path) -> PluginLoadFuture<'a>;

    /// Check if this loader can handle the given file
    fn can_load(&self, path: &Path) -> bool;

    fn unload(&self, data: Box<dyn Any + Send + Sync>) -> PluginUnloadFuture<'_>;

    /// Checks if the plugin can be safely unloaded.
    fn can_unload(&self) -> bool;
}

/// Unified loader error type
#[derive(Error, Debug)]
pub enum LoaderError {
    #[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(

View on GitHub (pinned to 8d4639e25a)