Skip to main content

Multiple Root USD Files

Error code: MORE_THAN_ONE_ROOT_USD_FILE

"It looks like there was more than one USD file in the root of the directory that you uploaded. Please ensure there is one USD file in your root directory, and all others must be in subdirectories."

What This Means​

Miris found more than one USD file directly in the root of your upload. Only one USD file can exist at the root level — it acts as the single entry point for the asset. Additional USD files must be in subdirectories.

Common Causes​

  • Multiple USD files (e.g., separate layer files or variants) were placed flat in the root rather than in a structured folder hierarchy
  • Houdini: The USD ROP exports both a main asset.usd and a asset_payload.usd (or asset_geo.usd) into the same output directory when payload export is enabled — both land at the root level
  • Maya: Enabling "Export as Payload" in the USD Export dialog emits a _payload.usd file alongside the main USD file in the same directory
  • Omniverse: Stages saved locally from Omniverse can produce a flat structure with stage.usd and one or more sublayer files side-by-side at the root

How to Fix It​

  1. Decide which USD file should be your root file — this is typically the top-level scene or assembly file (e.g., asset.usd, not asset_payload.usd)
  2. Move all other USD files into a subfolder (e.g., a payloads/ or layers/ folder inside your root directory)
  3. Update the references inside your root USD file to point to the new locations. Open the root file in a text editor (.usda files are plain text) or run usdcat yourfile.usd in a terminal — look for subLayers, references =, or payload = lines and update the paths to include the subfolder (e.g., @./payloads/asset_payload.usd@)
  4. Re-upload the corrected folder
tip

Think of the root USD file as the "front door" to your asset — it's the one Miris opens first. All other USD files (layers, geometry payloads, sub-assemblies) should live inside subfolders and be referenced from the root file. If multiple USD files sit side-by-side at the top level, Miris doesn't know which one to start from.

Still seeing this error after following the steps above? Contact support with your asset name and a description of what you've tried.