nautechsystems/nautilus_trader · error

Failed to import json: {e}

Error message

Failed to import json: {e}

What it means

py_json_deserialize_custom_data serializes a custom data value to JSON, then uses Python's json module inside the deserialization callback. If importing the json module fails (broken/limited Python environment, embedded interpreter without stdlib), the error is wrapped as 'Failed to import json: {e}'.

Source

Thrown at crates/model/src/python/data/mod.rs:357

    };
    Ok(custom)
}

/// Deserializes JSON value to `CustomData` via the data class's `from_json`.
#[cfg(feature = "python")]
fn py_json_deserialize_custom_data(
    data_class: &pyo3::Py<pyo3::PyAny>,
    value: &serde_json::Value,
) -> Result<std::sync::Arc<dyn crate::data::CustomDataTrait>, anyhow::Error> {
    use std::sync::Arc;

    use crate::data::PythonCustomDataWrapper;

    pyo3::Python::attach(|py| {
        let json_str = serde_json::to_string(&value)?;
        let json_module = py
            .import("json")
            .map_err(|e| anyhow::anyhow!("Failed to import json: {e}"))?;
        let py_dict = json_module
            .call_method1("loads", (json_str,))
            .map_err(|e| anyhow::anyhow!("Failed to parse JSON: {e}"))?;

        let instance = data_class
            .bind(py)
            .call_method1("from_json", (py_dict,))
            .map_err(|e| anyhow::anyhow!("Failed to call from_json: {e}"))?;

        let wrapper = PythonCustomDataWrapper::new(py, &instance)
            .map_err(|e| anyhow::anyhow!("Failed to create wrapper: {e}"))?;

        Ok(Arc::new(wrapper) as Arc<dyn crate::data::CustomDataTrait>)
    })
}

/// Encodes `CustomData` items to `RecordBatch` via Python `encode_record_batch_py`.
#[allow(unsafe_code)]

View on GitHub (pinned to 18893faf8b)

Solutions

  1. Fix the embedded Python environment so `import json` works (set PYTHONHOME/PYTHONPATH correctly or ship the full stdlib).
  2. Remove or rename any local json.py module shadowing the stdlib on sys.path.
  3. Verify in the same interpreter: python -c "import json"; if it fails, reinstall/repair the Python runtime.

Example fix

// before: interpreter without usable stdlib -> import fails
let instance = py_json_deserialize_custom_data(data_class, value)?;
// after: verify environment at startup
// $ python -c "import json"   # must succeed
// set PYTHONHOME to the prefix of the Python that ships the stdlib
std::env::set_var("PYTHONHOME", "/usr");
let instance = py_json_deserialize_custom_data(data_class, value)?;
Defensive patterns

Strategy: validation

Validate before calling

// run once at startup before registering custom data classes
pyo3::Python::attach(|py| {
    py.import("json").map_err(|e|
        anyhow!("embedded Python cannot import json stdlib: {e}; check PYTHONHOME/PYTHONPATH"))
})?;

Try / catch

match py_json_deserialize_custom_data(data_class, value) {
    Ok(v) => v,
    Err(e) if e.to_string().contains("Failed to import json") => {
        // repair embedded interpreter stdlib, then retry once
        repair_python_env()?;
        py_json_deserialize_custom_data(data_class, value)?
    }
    Err(e) => return Err(e),
}

Prevention

When it happens

Trigger: Registering a custom data class via register_custom_data_class and then deserializing a value when the embedded Python interpreter cannot import the stdlib json module — e.g. PYTHONHOME/PYTHONPATH misconfigured in an embedded build, frozen/trimmed Python distributions, or a stdlib shadowed by a local file named json.py.

Common situations: Deploying nautilus in a slim container with an incomplete Python installation; embedding the Rust engine with a Python interpreter missing its stdlib; a user module named json.py shadowing the stdlib on sys.path.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

AI-assisted analysis of nautechsystems/nautilus_trader@18893faf8b (2026-09-08). Data as JSON: /api/errors/7205003f9a49b147. Report an issue: GitHub.