Skip to main content

SerializeReference repair

References lost after a class rename are found across the project and repaired in groups.

Quick start​

Choosing a repair method​

Where to repairData preservedUndo
Fix in an asset's InspectorEntry data in the fileNone
Fix in a scene or Prefab ModeOnly flat top-level fieldsUndo until saved
Asset ReferencesEntry data in the fileNone
Project ReferencesGroup entries' data in the filesUndo button in the rewrite summary

Project References also repairs the names that SerializableType and SerializableMonoScript fields store, see Type names. To catch new breakages in the Editor, before a build or in CI, see Build and CI checks.

Fix in the Inspector​

After a class is renamed, moved or deleted, the field shows Missing type, while the data stays in the asset.

A missing reference with Fix and the → Pistol suggestion in the InspectorA missing reference with Fix and the → Pistol suggestion in the Inspector

ActionWhat it does
FixOpens the class picker, including classes hidden with Hidden
→ PistolAssigns the suggested class; the tooltip gives the reason
warning

In a scene or Prefab Mode, Fix brings back only flat top-level fields: nested objects, arrays, lists, vectors, colours and object references get their default values.

When there is no Fix​

CaseWhat to do
Several objects selectedSelect one: until then Missing type is not shown
Unsaved changes in the scene or Prefab ModeSave: until then the field shows <None> without Missing type
Unsaved list edits that leave it unclear which element a slot holds, such as deleting one of two missing elements side by sideSave: until then the slot shows <None> without Missing type
Prefab instance, class stored in the source prefabRepair the source prefab; the tooltip names it
Prefab instance, class set through an overrideChoose a new class on the instance or revert the override

Missing elements in lists​

A save that resizes a list, and every save of a prefab, writes the list's missing elements as <None> and drops their data. FastTools puts them back right after the save. It matches the other elements by their rid, so after you move, delete, duplicate or add an element, a missing element returns between the same neighbours. The Console lists the restored elements.

CaseWhat happens
You set a missing element to <None>, pick another class or paste over itIt stays replaced, also after a script reload. After Edit → Undo of that pick the next save keeps it
You delete an element that sits among other missing or <None> elementsThe saved file doesn't say which one went: the <None> elements and the first missing ones stay. The Console warns about the missing element left out and gives its index and rid, so you can take it from version control
You make several edits to the list between two savesThe data comes back, but in the most likely slot, which is not always the original one. The Console names the slot of every restored element and marks the least certain ones slot guessed
Lists inside another reference or a nested class, loaded scenes, Prefab ModeNot guarded

Project References: repair a group​

Open Tools → Aspid 🐍 → FastTools → Project References; Asset References is the neighbouring tab of the same window. Scan Project reads the .prefab, .asset, .unity, .controller and .playable files under Assets/, apart from Excluded scan folders. A progress bar shows each sweep; Cancel stops the scan and keeps the earlier results. A group lists its first 200 entries, and Show more adds the next 200.

Project References: Broken groups with Fix all and Smart Fix, a Renamed group with Migrate allProject References: Broken groups with Fix all and Smart Fix, a Renamed group with Migrate all

Group actions​

GroupHeader buttonRow under the header
Missing typeFix all ▼ — pick a class for every entrySmart Fix → Game.Weapons.Pistol — apply the suggested class; the tooltip gives the reason
Renamed with [MovedFrom]Reassign all ▼ — pick a different class instead of the new nameMigrate all → Game.Weapons.Crossbow — write the new name, see Migrations

The Fix all, Reassign all and Migrate all labels show the number of entries in the group, for example Fix all (4) ▼ and Migrate all (4) → Game.Weapons.Crossbow.

Every action asks for Rewrite. <None> in the class picker clears the group's references and deletes their data, fields sharing the same rid included; it asks for Clear and has no Undo. In open and unsaved files it clears the references in memory, until you save.

What repair preserves​

A repair rewrites only the entry's class, namespace and assembly; its data and rid stay.

warning

When the group's fields have different types, the pick may not fit every entry: incompatible ones become null on reimport.

The summary after a rewrite has Undo: it restores the old class on entries that still hold the new one. It is gone after Rescan, closing the window or a domain reload; Edit → Undo does not revert a rewrite.

Prefab instance overrides​

A missing class set through a prefab instance override — in a variant, a nested prefab or an instance in a scene — is listed in a separate Prefab instance overrides section.

Prefab instance overrides card with a missing GhostRailgun in the EliteLoadout variantPrefab instance overrides card with a missing GhostRailgun in the EliteLoadout variant

Fix all, Smart Fix, Migrate all and <None> do not rewrite these entries: pick a new class on the instance in the Inspector, or revert the override. Asset References does not show references that exist only in overrides.

Type names​

A SerializableType or SerializableMonoScript field whose stored name no longer resolves goes to a group marked type name. A group holds one stored name and lists its fields by asset and field path.

ActionWhat it does
Fix all ▼Opens the type picker with the constraint of the fields and writes the picked type to every field of the group
Smart Fix → Game.Combat.SpearWrites the only compatible type with the same class name

A SerializableMonoScript field also gets the script of the picked type. A prefab instance override is rewritten as well, because it stores the name as a plain value.

The scan does not find [TypeSelector] strings: repair them in the Inspector, or with Change ▼ in Asset References.

Asset References: inspect one asset​

Open Tools → Aspid 🐍 → FastTools → Asset References and assign a saved prefab, ScriptableObject or scene to the field next to Rescan. Or select an asset in the Project window and choose Assets → Aspid 🐍 → FastTools → Asset References, from the main menu or the right-click menu, or press Alt+Shift+R (Option+Shift+R on macOS): the tab opens on that asset. Clicking an entry row in Project References opens its asset here.

Asset References with a missing GhostCrossbow, a shared Pistol and an orphaned Railgun entryAsset References with a missing GhostCrossbow, a shared Pistol and an orphaned Railgun entry

LabelMeaning
Band with Fix Missing ▼The stored class is not found; the button opens the class picker
Smart Fix → Game.Weapons.Pistol rowA class picked as by Smart Fix in Project References
Migrate → Game.Weapons.Crossbow row under a Fix ▼ bandThe class was renamed with [MovedFrom]: the row writes the new name, Fix ▼ picks a different class
Band with Change ▼, Assign ▼ or Assign Required ▼Changes the class of a healthy reference, fills an empty or required field; the asset is saved at once
● sharedSeveral fields point at one instance; dots of the same colour mark the connected fields
type name in a card's footerA [TypeSelector] string, SerializableType or SerializableMonoScript field; it is listed whether it holds a type or not
children on another card in a card's footerThe children of this reference are drawn once, under its first card that is not below a missing type; this card is another field that points at it
One-line row with a field name and Assign ▼An optional field that holds no reference or type, in its place among the fields; an empty [Required] field keeps an amber card
Orphaned sectionEntries no field points at; Clear in a card's header deletes one from the file after you confirm, without Undo
Heading with ▼The object whose fields the cards below are, such as Player › Loadout; click it to fold its cards
Unsaved changes with Save AssetThe asset has edits that are not saved, and the map reads the saved file: the button saves the asset and maps it again

Fix Missing, Smart Fix and Migrate write the class to the file at once, and Edit → Undo does not revert it.

GhostWeapon is repaired as Pistol in Asset ReferencesGhostWeapon is repaired as Pistol in Asset References

Migrations with MovedFrom​

When CrossbowLauncher is renamed to Crossbow with [MovedFrom], Unity loads the old references itself. Migrate all writes the new name into the files so the attribute can be removed:

In the file — before Migrate allAfter
type: {class: CrossbowLauncher, …}type: {class: Crossbow, …}

A group becomes a pending migration only when exactly one class lists the old name in [MovedFrom], that class fits the field, and the stored class is not a closed generic.

Remove [MovedFrom] only when no file stores the old name any more. Migrate all does not rewrite it:

  • in prefab instance overrides;
  • in Excluded scan folders and in files outside Assets/;
  • in the files listed under limitations.

Limitations​

WhereLimitation
Open scenes, Prefab Mode, unsaved and locked filesFix all, Smart Fix and Migrate all skip them: save and close the file, or use Fix in the Inspector with its data-transfer limitations
Scenes and fields under a missing parent referenceAsset References changes only missing types; in a scene it lists only the empty required type names
Binary assets and unfetched Git LFS filesNot scanned: Scan Project counts them and the Console lists them, Asset References shows Not scanned; use Force Text and fetch LFS files
Files last saved before Unity 2021.2Their managed references are not read: save the files again in the current Unity version
More than 1000 reference cards in one windowAsset References draws the first 1000 and says how many it left out; Project References repairs missing types without this limit