Pumpkin-MC/Pumpkin · error · PluginInitError

Failed to read plugin file

Error message

Failed to read plugin file: {0}

What it means

This is `PluginInitError::FileReadFailed`, wrapping `std::io::Error`. The loader could not read the plugin file from disk before handing it to wasmtime. The OS-level cause (not found, permission denied, is-a-directory) is in the wrapped io::Error.

Solutions

  1. Verify the .wasm file exists at the configured plugins path (ls the directory)
  2. Fix file permissions (chmod/chown) so the server user can read it
  3. Correct the plugin path/filename in your server config or plugin directory
  4. Re-download/rebuild the plugin if the file is truncated or empty

Example fix

// before
let bytes = std::fs::read("plugins/teleport.wasm")?;
// after: check first
if !path.exists() { eprintln!("plugin missing: {}", path.display()); }
let bytes = std::fs::read(&path)?;
Defensive patterns

Strategy: validation

Validate before calling

let path = Path::new(plugin_path);
if !path.is_file() { bail!("plugin file not found: {}", plugin_path); }
let meta = std::fs::metadata(path)?;
if meta.permissions().mode() & 0o400 == 0 { bail!("plugin file not readable"); }

Type guard

fn readable_plugin(path: &Path) -> bool { path.is_file() && File::open(path).is_ok() }

Try / catch

match init::read_plugin_file(path) {
    Err(PluginInitError::FileReadFailed(e)) => eprintln!("cannot read plugin {}: {e}", path.display()),
    other => other,
}

Prevention

When it happens

Trigger: `std::fs::read` (or similar) on the plugin path during WASM plugin load fails — path doesn't exist, no read permission, or path points at a directory.

Common situations: Typo in plugin name in the plugins directory, file deleted while server ran, wrong permissions after extracting an archive as root, config pointing at the wrong folder.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

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

Appendix: source

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

};
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}")]
    CacheCreationFailed(wasmtime::Error),
}

View on GitHub (pinned to 8d4639e25a)