Unity-Technologies/UnityCsReference · error · NotImplementedException

HierarchyProperty is deprecated. Use HierarchyIterator inste

Error message

HierarchyProperty is deprecated. Use HierarchyIterator instead.

What it means

The HierarchyProperty.ancestors property getter unconditionally throws NotImplementedException. HierarchyProperty is being deprecated in favor of HierarchyIterator; the ancestors member was not migrated and is a dead stub that always fails at runtime.

Source

Thrown at Editor/Mono/HierarchyProperty.bindings.cs:133

            Dispose(true);
            GC.SuppressFinalize(this);
        }

#pragma warning disable UA5000 // The Avoid Finalizer Analyzer produces compile errors for any new finalizers. This pre-existing finalizer declaration has been suppressed, but should be rewritten if possible.
        ~HierarchyProperty() { Dispose(false); }
#pragma warning restore UA5000

        extern EntityId entityId { get; }
        public int instanceID => entityId;
        public extern Object pptrValue { [FreeFunction("HierarchyPropertyBindings::PPtrValue", HasExplicitThis = true)] get; }
        public extern string name { get; }

        [FreeFunction("HierarchyPropertyBindings::GetScene", HasExplicitThis = true, ThrowsException = true)]
        public extern Scene GetScene();

        public extern bool hasChildren { [NativeName("HasChildren")] get; }
        public extern int depth { get; }
        public int[] ancestors { get { throw new System.NotImplementedException("HierarchyProperty is deprecated. Use HierarchyIterator instead."); } }
        public extern int row { get; }
        public extern int colorCode { get; }

        public bool IsExpanded(int[] expanded) => throw new System.NotImplementedException("HierarchyProperty is deprecated. Use HierarchyIterator instead.");

        public extern string guid { [FreeFunction("HierarchyPropertyBindings::GetGuid", HasExplicitThis = true)] get; }
        public extern GUID assetGUID { [FreeFunction("HierarchyPropertyBindings::GetAssetGUID", HasExplicitThis = true)] get; }
        public extern bool alphaSorted { [NativeName("IsAlphaSorted")] get; set; }
        public extern bool showSceneHeaders { [NativeName("IsShowingSceneHeaders")] get; [NativeName("SetShowingSceneHeaders")] set; }
        public extern bool isSceneHeader { [NativeName("IsSceneHeader")] get; }
        public extern bool isValid { [NativeName("IsValid")] get; }
        public extern bool isMainRepresentation { [NativeName("IsMainAssetRepresentation")] get; }
        public extern bool hasFullPreviewImage { [NativeName("HasFullPreviewImage")] get; }
        public extern IconDrawStyle iconDrawStyle { get; }
        public extern bool isFolder { [NativeName("IsFolder")] get; }
        public extern GUID[] dynamicDependencies { get; }

        public bool Next(int[] expanded) => throw new System.NotImplementedException("HierarchyProperty is deprecated. Use HierarchyIterator instead.");

View on GitHub (pinned to 225b0fbdb5)

Solutions

1. Replace HierarchyProperty traversal with HierarchyIterator, which provides equivalent ancestor and depth APIs.
2. If only ancestor IDs are needed, compute them from HierarchyIterator by walking Parent() calls.

Example fix

// before
int[] ancestors = prop.ancestors;
// after
using var iter = new HierarchyIterator(...);
var ancestors = new List<int>();
while (iter.Parent()) ancestors.Add(iter.instanceID);

// Do not access HierarchyProperty.ancestors — it always throws.
// Migrate to HierarchyIterator for ancestor information.

When it happens

Trigger: Reading the HierarchyProperty.ancestors property on any HierarchyProperty instance.

Common situations: Existing editor extensions or hierarchy-traversal code that reads the ancestors array after a Unity upgrade that introduced HierarchyIterator.

Related errors

• Get GetPickingIncludeExcludeList is obsolete, use GetPicking
• Get GetSelectionOutlineIncludeExcludeList is obsolete, use G
• Use DrawOutline(EntityId[], EntityId[], Color, Color, float)
• Use DrawOutline(EntityId[], Color, float) instead.
• Facebook support was removed in 2019.3

AI-assisted analysis of Unity-Technologies/UnityCsReference@225b0fbdb5 (2026-08-13). Data as JSON: /api/errors/208ad609b62b5a23. Report an issue: GitHub.