AvaloniaUI/Avalonia · error · InvalidOperationException

Unknown binding path element type

Error message

Unknown binding path element type {element.GetType().FullName}

What it means

Thrown as InvalidOperationException during CompiledBindingPath.Build when an ICompiledBindingPathElement in the path does not match any of the known element-type cases in the switch. Each path element must be a recognized type (PropertyElement, MethodAsDelegateElement, ArrayElementPathElement, stream/typecast/ancestor/name/self/templated-parent elements). An unknown element type indicates a version mismatch or an unsupported custom element injected into the path.

Solutions

1. Only use the public CompiledBindingPathBuilder methods (Property, Method, Command, Stream, etc.) to construct paths so all elements are recognized.
2. If on a custom/older Avalonia build, update to a version whose Build() switch handles your element type.
3. Do not inject custom ICompiledBindingPathElement implementations; extend the binding pipeline through supported extension points instead.

Example fix

// before — custom element injected via reflection
builder._elements.Add(new MyCustomElement());
path.Build(); // throws: unknown element type
// after — use a supported builder method
builder.Property(propInfo, accessorFactory);

// Only use public CompiledBindingPathBuilder methods; do not inject custom elements.
// If extending, ensure Build()'s switch handles your element type.

static bool IsKnownElement(ICompiledBindingPathElement e) =>
    e is PropertyElement or MethodAsDelegateElement or MethodAsCommandElement
    or ArrayElementPathElement or VisualAncestorPathElement or AncestorPathElement
    or SelfPathElement or ElementNameElement or IStronglyTypedStreamElement
    or ITypeCastElement or TemplatedParentPathElement;

try { path.Build(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("Unknown binding path element"))
{ /* remove unsupported custom element or upgrade Avalonia */ }

When it happens

Trigger: A CompiledBindingPathBuilder accumulates an ICompiledBindingPathElement subclass that Build() does not handle. In normal use the builder only adds known element types, so this fires when custom/unsupported elements are injected, or when a newer path element type is fed to an older Avalonia build.

Common situations: Using reflection to add a custom ICompiledBindingPathElement to a CompiledBindingPathBuilder. Version mismatch: code compiled against a newer Avalonia adds an element type the runtime build cannot handle. Internal API misuse by a source generator or extension.

Related errors

• Unable to parse ' ': expected an instance of ' ' but got '…
• Bad format specifier.
• BindingErrorType may not be None
• BindingValue has no value.
• Cannot add value to DoNothing binding value.

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

Appendix: source

Thrown at src/Avalonia.Base/Data/CompiledBindingPath.cs:84

                        node = null;
                        isRooted = true;
                        break;
                    case ElementNameElement name:
                        node = new NamedElementNode(name.NameScope, name.Name);
                        isRooted = true;
                        break;
                    case IStronglyTypedStreamElement stream:
                        node = new StreamNode(stream.CreatePlugin());
                        break;
                    case ITypeCastElement typeCast:
                        node = new FuncTransformNode(typeCast.Cast);
                        break;
                    case TemplatedParentPathElement:
                        node = new TemplatedParentNode();
                        isRooted = true;
                        break;
                    default:
                        throw new InvalidOperationException($"Unknown binding path element type {element.GetType().FullName}");
                }

                if (node is not null)
                    result.Add(node);
            }


            for (var i = 0; i < negated; ++i)
                result.Add(new LogicalNotNode());
        }

        internal IEnumerable<ICompiledBindingPathElement> Elements => _elements;

        /// <inheritdoc />
        public override string ToString()
            => string.Concat((IEnumerable<ICompiledBindingPathElement>)_elements);
    }

View on GitHub (pinned to 11c5427268)