{"record":{"id":"af5f9724c50d30d7","repo":"FyroxEngine/Fyrox","slug":"gltf-material-failed-to-import-reason-err","errorCode":null,"errorMessage":"glTF material failed to import. Reason: {err:?}","messagePattern":"glTF material failed to import\\. Reason: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"fyrox-impl/src/resource/gltf/material.rs","lineNumber":197,"sourceCode":"/// * `textures`: A slice containing a [TextureResource] for every texture defined in the document, in that order, so that\n/// a texture can be looked up using the index of a texture within the document. Materials in glTF specify their target\n/// textures by their index within the node list of the document, and these indices need to be translated into handles.\n///\n/// * `buffers`: A slice containing a list of byte-vectors, one for each buffer in the glTF document.\n/// Animations in glTF make reference to data stored in the document's list of buffers by index.\n/// This slcie allows an index into the document's list of buffers to be translated into actual bytes of data.\n///\n/// * `resource_manager`: A [ResourceManager] makes it possible to access shaders and create materials.\npub async fn import_materials(\n    gltf: &Document,\n    textures: &[TextureResource],\n) -> Result<Vec<MaterialResource>> {\n    let mut result: Vec<MaterialResource> = Vec::with_capacity(gltf.materials().len());\n    for mat in gltf.materials() {\n        match import_material(mat, textures).await {\n            Ok(res) => result.push(res),\n            Err(err) => {\n                Log::err(format!(\"glTF material failed to import. Reason: {err:?}\"));\n                result.push(MaterialResource::new_ok(\n                    Uuid::new_v4(),\n                    ResourceKind::Embedded,\n                    Material::default(),\n                ));\n            }\n        }\n    }\n    Ok(result)\n}\n\nasync fn import_material(\n    mat: gltf::Material<'_>,\n    textures: &[TextureResource],\n) -> Result<MaterialResource> {\n    let shader: ShaderResource = GLTF_SHADER.resource.clone();\n    if !shader.is_ok() {\n        return Err(GltfMaterialError::ShaderLoadFailed);","sourceCodeStart":179,"sourceCodeEnd":215,"githubUrl":"https://github.com/FyroxEngine/Fyrox/blob/76c91aad8eca488ce527b1af707be8b3b24ad72d/fyrox-impl/src/resource/gltf/material.rs#L179-L215","documentation":"When importing a glTF material fails (e.g. bad texture reference or unsupported material feature), the loader logs this error, discards the reason, and substitutes a default white Material with an Embedded resource kind so the rest of the model still loads. Surfaces using that material render untextured/default.","triggerScenarios":"import_material during import_from_slice returns Err: referenced texture images missing or unreadable, unsupported PBR extensions, invalid texture coordinates, or texture import/decode failure in the async texture loading step.","commonSituations":"glb/gltf files referencing external .bin/image files that were not shipped alongside, KTX/basis-compressed textures without the matching feature enabled, exotic material extensions (clearcoat, transmission) unsupported by the engine version.","solutions":["Ship all external texture/bin files referenced by the .gltf next to it, or use .glb (self-contained)","Enable the required texture-compression features or re-export textures as PNG/JPEG","Re-export with only core glTF 2.0 PBR material (metallic-roughness) without extra extensions","Check the log for the underlying texture/import error and fix that asset"],"exampleFix":"// before: material silently defaulted to white\nlet model = resource_manager.request::<Model>(\"scene.gltf\");\n// after: reassign expected material after load if defaults detected\nlet model = resource_manager.request::<Model>(\"scene.gltf\");\nif let ResourceState::Ok(m) = model.state() {\n    for (_, mesh) in m.get_scene().iter().flat_map(|n| n.mesh().into_iter()) {\n        for surface in mesh.surfaces() {\n            if is_default_white_material(surface.material()) {\n                surface.set_material(my_expected_material.clone());\n            }\n        }\n    }\n}","handlingStrategy":"fallback","validationCode":"// Verify all referenced textures exist before loading a .gltf\nlet doc = gltf::Gltf::from_slice(&bytes)?;\nfor image in doc.images() {\n    if let gltf::image::Source::Uri { uri, .. } = image.source() {\n        assert!(base_dir.join(uri).exists(), \"missing texture: {}\", uri);\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use .glb (embedded) to avoid missing external texture files","Check logs for material import errors whenever loading new assets","Limit materials to core PBR metallic-roughness unless features are enabled","Enable texture-compression cargo features if using KTX/basis textures"],"tags":["gltf","material","asset-import","fallback"],"backgroundTag":"asset-import-failed","analyzedSha":"76c91aad8eca488ce527b1af707be8b3b24ad72d","analyzedAt":"2026-09-10T16:04:01.633Z","contentChangedAt":"2026-09-10T16:04:01.633Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}