Skip to main content
Version: Next (dev)

Repairing Source Paths

Most assets are made from a source file: a texture from a PNG, a mesh from an FBX, a sound from a WAV. The asset document stores the path of that file. When the file is moved or renamed outside the asset document, the stored path points nowhere, and the asset can't be transformed any more.

The editor notices such broken paths, shows where they are, and can find out where the files went and update the paths for you.

Seeing missing source files​

The editor marks assets with a missing source file in several places:

  • Asset Browser strip. A bar in the Asset Browser says N assets have a missing source file. Moved? The paths can be repaired. with a Repair Source Paths... button.
  • Tile badge. The asset's tile shows a red ? badge, separate from the failed-transform state (a version control badge takes precedence). The tile's tooltip lists the missing files and says Right-click > Repair Source Paths... if the file was moved.
  • Asset window. The state chip in the header of the asset's window reads Source file missing: name. Click to Repair. Click it to repair the asset.
  • Project checks. In the Scripts panel, a project check problem ending in (double-click to repair the source path) opens the repair dialog for that asset when you double-click it.

Repairing paths​

Open the Repair Source Paths dialog in one of these ways:

FromScope
The strip's Repair Source Paths... button, or the Asset Browser background's context menu, Repair Source Paths... (N assets affected)Every asset in the project.
Right-click a folder, Repair Source Paths in Folder...Assets in that folder and below.
Right-click an asset, Repair Source Paths..., or the asset window's chipThat asset only. Also repair assets that use the same missing files adds the other assets that point to the same files.

If nothing is broken, the editor says No asset has a source path that points to a missing file.

Reviewing the plan​

The dialog lists one row per broken source path, with the Asset, the Property that holds the path, the Missing Path, the proposed New Path and the State. Nothing is written until you click Apply.

The editor looks for each missing file in the project's data directories, by name and location. It ranks what it finds:

  1. a move the editor made itself and therefore knows about,
  2. a folder change that other repairs in the same plan show, for example Textures/Old moved to Textures/New,
  3. the only file in the data directories with that name,
  4. one of several files with that name,
  5. a file with the same name and another extension.

Only a known move or a unique match is chosen automatically. Everything else waits for you.

StateMeaning
ReadyA new path is chosen. The row is applied.
Choose oneSeveral candidates were found. Pick one in the New Path dropdown (Choose...).
Not foundNo candidate was found. Use Browse... to pick the file. It has to be inside a data directory of the project.
UnsavedThe asset is open with unsaved changes. Save or discard them first; until then the row can't be applied.
SkippedNothing to repair, for example because the value is inherited from a parent asset (repair the parent), or the file exists.

Use the folder change of other paths turns the folder inference (rank 2) on and off. When it is on, the option shows the folder change it uses.

Applying​

Apply updates every selected row. The repair is all or nothing: if one document can't be saved, the documents already changed are restored, so the project is never left half-repaired.

The results list every row with its outcome and reason:

OutcomeMeaning
UpdatedThe asset now uses the new path.
DeclinedNot applied, for example because you did not select the row, no file was chosen, or the document has unsaved changes.
FailedAn error, for example the document could not be opened or read.
Rolled backThe path was written, then restored because another document failed.

Transform Repaired Assets transforms the updated assets right away. Retry returns to the review step, Copy Log copies the results to the clipboard (they are also written to the log), and Close closes the dialog.

Moving files in the Asset Browser​

When you move or rename a source file, or a folder with source files, in the Asset Browser, the editor knows where the files went. If assets use them, the Repair Source Paths dialog opens right after the move with the new paths filled in. Click Apply to update the assets, or Not now to leave them as they are.

To skip the question, turn on Always update after a move, without asking in the dialog, or the Update Source Paths After Move preference in Tools > Preferences... > Application: General (off by default). The editor then updates the paths without a dialog whenever every new path is certain. If some paths could not be updated, it tells you which.

Moving files in Windows Explorer or with version control is not seen as a move. The paths then show up as missing, and the dialog finds the files by name.

Troubleshooting​

SymptomCause
A row stays UnsavedThe asset is open with unsaved changes. Save or close it, then click Retry.
Browse... says the file is not in a data directoryAssets can only use source files inside the project's data directories. Copy the file into one first.
Everything was Rolled backOne document could not be saved, for example because it is write-protected or the project is read-only. Fix that document and apply again.
A prefab instance or template asset is SkippedThe value is inherited. Repair the parent asset.

See Also​