FyroxEngine/Fyrox · error

Cannot obtain a reference to the plugin, because it is…

Error message

Cannot obtain a reference to the plugin, because it is unloaded!

What it means

PluginState::as_loaded_ref returns a reference to the DyLibHandle only when the plugin is in the Loaded state. If the dynamic library was unloaded (PluginState::Unloaded), the plugin's code is no longer mapped, so the method panics rather than return a dangling reference.

Solutions

1. Call as_loaded_ref only while the plugin is loaded; reload() first if it was unloaded
2. Check the PluginState enum (match on PluginState::Loaded) before access
3. Synchronize hot-reload unloading with the frame loop so no code touches the plugin while unloaded

Example fix

// before
let iface = plugin.as_loaded_ref();
// after
if let PluginState::Loaded(handle) = plugin.state() {
    let iface = handle.plugin();
}

let usable = !matches!(plugin.state(), PluginState::Unloaded);

fn loaded(p: &PluginState) -> Option<&DyLibHandle> { if let PluginState::Loaded(d) = p { Some(d) } else { None } }

When it happens

Trigger: Calling plugin.as_loaded_ref() (via DynamicPlugin/PluginState) after unload() was called, or constructing a state as Unloaded and reading it.

Common situations: Accessing the plugin during/after hot-reload unload; plugin reload racing with a render/update call; forgetting reload() before use.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Unsupported platform!
• Graphics context is uninitialized!
• Animation pool must be empty on load!
• Cast to failed!
• An object at index must be returned to a pool it was taken…

AI-assisted analysis of FyroxEngine/Fyrox@76c91aad8e (2026-09-10). Data as JSON: /api/errors/4f0f72f8cb8bb098. Report an issue: GitHub.

Appendix: source

Thrown at fyrox-impl/src/plugin/dylib.rs:294

        Ok(())
    }
}

/// Actual state of a dynamic plugin.
enum PluginState {
    /// Unloaded plugin.
    Unloaded,
    /// Loaded plugin.
    Loaded(DyLibHandle),
}

impl PluginState {
    /// Tries to interpret the state as [`Self::Loaded`], panics if the plugin is unloaded.
    pub fn as_loaded_ref(&self) -> &DyLibHandle {
        match self {
            PluginState::Unloaded => {
                panic!("Cannot obtain a reference to the plugin, because it is unloaded!")
            }
            PluginState::Loaded(dynamic) => dynamic,
        }
    }

    /// Tries to interpret the state as [`Self::Loaded`], panics if the plugin is unloaded.
    pub fn as_loaded_mut(&mut self) -> &mut DyLibHandle {
        match self {
            PluginState::Unloaded => {
                panic!("Cannot obtain a reference to the plugin, because it is unloaded!")
            }
            PluginState::Loaded(dynamic) => dynamic,
        }
    }
}

fn try_copy_library(source_lib_path: &Path, lib_path: &Path) -> Result<(), String> {
    info!(

View on GitHub (pinned to 76c91aad8e)