AvaloniaUI/Avalonia · error · ArgumentException

Unknown property {propertyName}

Error message

Unknown property {propertyName}

What it means

The base CompositionObject.StartAnimation is virtual and throws unconditionally; concrete composition types receive a source-generated override (CompositionGenerator.Generator.cs:557) that dispatches their declared animatable properties and falls through to this base throw for anything else. So the exception fires when the requested property name is not an animatable property of the object's concrete type.

Source

Thrown at src/Avalonia.Base/Rendering/Composition/CompositionObject.cs:65

        private static SimpleServerObject ThrowInvalidOperation() =>
            throw new InvalidOperationException("There is no server-side counterpart for this object");

        protected internal void Dispose()
        {
            if (!IsDisposed && Server != null)
                Compositor.DisposeOnNextBatch(Server);
            IsDisposed = true;
        }

        /// <summary>
        /// Connects an animation with the specified property of the object and starts the animation.
        /// </summary>
        public void StartAnimation(string propertyName, CompositionAnimation animation)
            => StartAnimation(propertyName, animation, null);
        
        internal virtual void StartAnimation(string propertyName, CompositionAnimation animation, ExpressionVariant? finalValue)
        {
            throw new ArgumentException("Unknown property " + propertyName);
        }

        /// <summary>Disconnects an animation from the specified property and stops the animation.</summary>
        /// <param name="propertyName">The name of the property to disconnect the animation from.</param>
        public void StopAnimation(string propertyName)
        {
            if (propertyName is null)
                throw new ArgumentNullException(nameof(propertyName));
            if (Server is not ServerObject srv)
                return;
            var prop = srv.GetCompositionProperty(propertyName) ?? throw new ArgumentException("Unknown property " + propertyName);
            srv.Animations?.RemoveAnimationForProperty(prop);
        }

        /// <summary>
        /// Starts an animation group.
        /// The StartAnimationGroup method on CompositionObject lets you start CompositionAnimationGroup.
        /// All the animations in the group will be started at the same time on the object.

View on GitHub (pinned to 11c5427268)

Solutions

1. Use a property name that exists and is animatable on the concrete type (e.g. "Opacity", "Offset", "Size", "RotationAngle", "Scale" on CompositionVisual).
2. Animate a CompositionVisual / CompositionSpriteVisual rather than a CompositionPropertySet or CompositionBrush.
3. Double-check spelling and casing of the property name against the type's documented animatable properties.
4. Prefer StartAnimation(propertyName, animation) with the explicit name over StartAnimationGroup when in doubt.

Example fix

// before
visual.StartAnimation("Opasity", anim); // typo -> Unknown property

// after
visual.StartAnimation("Opacity", anim);

// Validate the property name against the concrete type's known animatable properties.
static readonly HashSet<string> VisualAnimatable = new() { "Opacity", "Offset", "Size", "RotationAngle", "RotationAxis", "Scale", "AnchorPoint", "CenterPoint" };
if (!VisualAnimatable.Contains(propertyName))
    throw new ArgumentOutOfRangeException(nameof(propertyName));
visual.StartAnimation(propertyName, anim);

static bool IsAnimatable(CompositionObject o) => o is CompositionVisual;

try { visual.StartAnimation(propertyName, anim); }
catch (ArgumentException ex) when (ex.Message.StartsWith("Unknown property"))
{ /* log and fall back to a known-good property or skip animation */ }

When it happens

Trigger: Calling obj.StartAnimation("Foo", anim) where "Foo" is not a declared animatable property of the concrete composition type, or calling StartAnimation on a type that has no animatable properties at all (e.g. CompositionPropertySet, CompositionBrush).

Common situations: Typos or wrong casing in the property name, animating a read-only or non-animatable property, or targeting an object type (property sets, brushes) that does not support direct property animation.

Related errors

• Animation Target can't be null
• Transition elements have different parents.
• {nameof(KeySpline)} must have X coordinates >= 0.0 and <= 1.
• Invalid KeySpline X1 value. Must be >= 0.0 and <= 1.0.
• Invalid KeySpline X2 value. Must be >= 0.0 and <= 1.0.

AI-assisted analysis of AvaloniaUI/Avalonia@11c5427268 (2026-08-13). Data as JSON: /api/errors/9901e5d81f79e6ae. Report an issue: GitHub.