FyroxEngine/Fyrox · error

Visitor environment must contain serialization context!

Error message

Visitor environment must contain serialization context!

What it means

Fyrox scene nodes are created from a registry of constructor functions keyed by type UUID. During deserialization, read_node looks up this registry in the Visitor's blackboard (SerializationContext) and panics with this message if it was never installed. The library requires the caller to provide the serialization context before visiting scene data.

Solutions

1. Register the SerializationContext in the visitor blackboard before visiting, e.g. visitor.blackboard.register(serialization_context) or use visitor.environment.mapping.insert::<SerializationContext>(ctx).
2. Load scenes through SceneLoader / ResourceManager instead of calling visit on a raw Visitor, so the context is installed automatically.
3. If running tests, use the shared SerializationContext (via RESOURCE_STATE_SERIALIZATION_CONTEXT or the crate's test helpers) when constructing the visitor.

Example fix

// before
let mut visitor = Visitor::new();
node.save("scene.ron")?; // later read panics
// after
let mut visitor = Visitor::new();
visitor.blackboard.register(serialization_context.clone());
node.save("scene.ron")?;

assert!(visitor.blackboard.get_opt::<SerializationContext>().is_some(),
    "register SerializationContext before visiting");

When it happens

Trigger: Calling Node::visit / resource loading on a Visitor that was built without calling visitor.environment.mapping.insert or without using a loader that registers the SerializationContext (e.g. manually constructing a Visitor instead of using the resource manager or SceneLoader).

Common situations: Manually deserializing a saved scene with a hand-built Visitor; loading scenes in a test or editor tool that skipped Fyrox's standard resource-loading path; refactoring code that used to call a context-registering helper.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• Resource manager must be available when deserializing…
• Animation pool must be empty on load!
• Graphics context is uninitialized!
• only rectangle textures can be used as render target!
• Graph pool must be empty on load!

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

Appendix: source

Thrown at fyrox-impl/src/scene/node/container.rs:46

};
use fyrox_core::visitor::error::VisitError;

/// A wrapper for node pool record that allows to define custom visit method to have full
/// control over instantiation process at deserialization.
#[derive(Debug, Clone, Default, PartialEq, Reflect)]
#[reflect(type_uuid = "be27db20-c0b0-491e-9421-8b1ebc357b9a")]
pub struct NodeContainer(Option<Node>);

fn read_node(name: &str, visitor: &mut Visitor) -> Result<Node, VisitError> {
    let mut region = visitor.enter_region(name)?;

    let mut id = Uuid::default();
    id.visit("TypeUuid", &mut region)?;

    let serialization_context = region
        .blackboard
        .get::<SerializationContext>()
        .expect("Visitor environment must contain serialization context!");

    let mut node = serialization_context
        .node_constructors
        .try_create(&id)
        .ok_or_else(|| VisitError::User(format!("Unknown node type uuid {id}!")))?;

    node.visit("NodeData", &mut region)?;

    Ok(node)
}

fn write_node(name: &str, node: &mut Node, visitor: &mut Visitor) -> VisitResult {
    let mut region = visitor.enter_region(name)?;

    let mut id = node.id();
    id.visit("TypeUuid", &mut region)?;

    node.visit("NodeData", &mut region)?;

View on GitHub (pinned to 76c91aad8e)