Imported a model into Reality Composer Pro and it's the wrong size, appears black, or has no textures? Here's how to diagnose and fix each of these common asset problems.
After importing a model, three complaints come up again and again: it is the wrong size, it renders solid black, or its textures are missing.
They feel like the model is broken, but each has a specific, fixable cause rooted in scale, lighting, or materials.
The good news is that these are among the most predictable issues in the whole pipeline. Once you know where to look, they are quick to resolve.
This guide tackles each in turn, then gives you a workflow to prevent them from recurring on the next asset.
RealityKit works in meters. That single fact explains the majority of scale surprises.
A model authored in centimeters, millimeters, or arbitrary units will appear dramatically too large or too small when interpreted as meters. A chair meant to be one meter tall can become a hundred meters and swallow the whole scene.
The cleanest fix is at the source: export from your 3D tool with correct real-world scale and units. Getting this right upstream prevents a cascade of downstream corrections.
If you cannot re-export, adjust the scale on the entity in Reality Composer Pro or set it in code. Just be consistent, and pick one place to own scale so you are not fighting conflicting adjustments.
A model that renders completely black often is not broken at all; it simply has no light. Without meaningful lighting, many surfaces render dark.
Preview the model under conditions closer to your app's real environment, including appropriate lighting, before concluding the material is at fault.
If you are testing on device or in a specific scene, confirm the environment actually provides illumination. An empty scene with no light is a common false alarm.
Only after ruling out lighting should you move on to the material itself, because chasing a material bug that is really a lighting gap wastes time.
If lighting is fine and the surface is still black, the material is the likely cause. A missing base color or a texture wired into the wrong input can produce a black surface.
Open the material in the Shader Graph editor and inspect the connections. Confirm the base color input is actually receiving a valid color or texture.
A frequent culprit is a normal map or data texture routed into base color, or a color-space mismatch between color and data textures. Both can darken or ruin a surface.
Rebuild the essential connections from a known-good starting point: a plain base color first, then add maps one at a time, previewing after each so you catch the exact step that breaks it.
Missing textures usually mean the material's texture references did not come along with the model. USDZ typically packages textures together, which is why it is convenient, but loose USD may point at external files that were left behind.
Confirm that any referenced texture files are actually present in the project. If they are not, re-import the asset with textures included, or add the missing files.
When exporting from your 3D tool, prefer a format and settings that embed or correctly reference textures. This avoids the broken-link problem entirely.
If a texture exists but still does not show, re-check where it is wired in the material graph. A present-but-disconnected texture looks identical to a missing one.
Sometimes textures are present and connected but appear stretched, tiled oddly, or smeared across the surface. That points to texture coordinates rather than missing files.
The model's UV layout controls how a 2D texture maps onto 3D geometry. Bad or missing UVs produce distorted results no amount of material tweaking will fix.
Check the texture coordinate handling in the material graph first, since a wrong coordinate node can misplace an otherwise correct texture.
If the UVs themselves are the problem, fix them in your modeling or UV tool and re-import. This is one of the cases where the fix genuinely belongs upstream in a dedicated application.
Standardize on meters and real-world scale in your export settings. Deciding this once and applying it to every asset eliminates the most common problem before it starts.
Prefer USDZ for interchange when you want textures packaged together, and verify each import visually right away rather than trusting that it worked.
Build materials incrementally and preview after each change, so a black or broken surface is traced to a single step instead of a tangled graph.
Finally, keep a simple reference object of known size in your scene during authoring. It makes scale mistakes obvious at a glance and turns a frustrating hunt into an instant read.
If you have ruled out scale, lighting, references, and UVs and the surface still reads incorrectly, narrow the problem down methodically.
Start from a known-good baseline: assign a plain, simple material with just a base color and confirm the geometry itself renders correctly under light. If that looks right, the geometry is fine and the issue lives in the material.
From there, reintroduce one map at a time, previewing after each. The step that breaks the look tells you exactly which texture or connection is responsible.
If even the plain material looks wrong, the problem is more likely in the mesh, its normals, or its export. That is a signal to return to your 3D tool, check the model's normals and orientation, and re-export rather than continuing to tweak in Reality Composer Pro.
Reality Composer Pro is excellent for composing scenes, assigning materials, and previewing, and it will resolve most of these issues once you know where to look.
It is not a modeling or texturing suite, so problems rooted in geometry, UVs, or source textures are ultimately fixed in dedicated 3D software and re-imported.
It also does not build or ship your app. Once your model looks right, you still assemble the experience in Xcode, and distribution requires the Apple Developer Program.
When a fix is not obvious, verify against Apple's current documentation. Because the tooling evolves with Xcode and visionOS, matching the official, up-to-date guidance is the surest path to a correct result.
The practical rule of thumb is to fix each problem as close to its source as you can. Presentation issues belong in Reality Composer Pro, while anything baked into the geometry or the exported file belongs upstream, and shipping belongs in Xcode.
RealityKit works in meters, so a model authored in other units is misinterpreted. Export with correct real-world scale from your 3D tool, or adjust the entity's scale consistently in one place.
First rule out lighting—an unlit scene renders many surfaces dark. If lighting is fine, check the material for a missing base color, a texture wired into the wrong input, or a color-space mismatch.
The texture references likely didn't come along. USDZ usually packages textures together, while loose USD may point at external files. Confirm the files are present and correctly referenced, and re-import with textures included if needed.
That's typically a UV or texture-coordinate issue rather than a missing file. Check the coordinate nodes in the material graph, and fix the model's UV layout in your modeling tool if necessary.
Scale, lighting, and material wiring can often be handled in Reality Composer Pro, but problems rooted in geometry, UVs, or source textures are best fixed upstream in dedicated 3D software and re-imported.