Skip to main content

Binding debugging

Binding error logging​

Avalonia logs binding errors to the trace output. In a debug build, these messages appear in the IDE Output window or the console. Here is an example of a typical binding error:

[Binding] Error in binding to 'Avalonia.Controls.TextBlock'.'Text': 'Could not find a matching property accessor for 'UserNam' on 'MyApp.ViewModels.MainViewModel'

This message tells you:

  • The target control and property (TextBlock.Text)
  • What went wrong (Property UserNam not found, likely a typo for UserName)
  • The source type being searched (MainViewModel)

Enabling verbose binding logging​

To see all binding activity (not just errors), configure the logging level in the Program.cs file of your project. With this configuration, logs record every binding resolution, value change, and fallback applied.

public static AppBuilder BuildAvaloniaApp()
    => AppBuilder.Configure<App>()
        .UsePlatformDetect()
        .LogToTrace(LogEventLevel.Warning)
        .LogToTrace(LogEventLevel.Verbose, LogArea.Binding);

Common binding problems​

Property not found​

Symptom: The control shows nothing or a fallback value. The log shows "Could not find a matching property accessor."

Causes:

  • Typo in the binding path.
  • The data context is not the type you expect.
  • The property is not public.

Fix: Verify the property name. Check the DataContext with DevTools.

DataContext is null​

Symptom: All bindings on a control produce no value.

Causes:

  • The data context was never set.
  • The data context was set on the wrong element.
  • A parent control has DataContext="{Binding SomeProperty}" where SomeProperty is null.

Fix: Use DevTools to inspect the DataContext at the control level.

Binding mode mismatch​

Symptom: Changes in the UI do not propagate to the view model, or vice versa.

Causes:

  • The default binding mode for the property is OneWay, but you need TwoWay.
  • The source property does not raise PropertyChanged.

Fix: Set Mode=TwoWay explicitly. Verify the view model implements INotifyPropertyChanged.

<TextBox Text="{Binding Name, Mode=TwoWay}" />

Compiled binding type mismatch​

Symptom: Build error "Cannot resolve property" or "Binding path is not valid for type."

Causes:

  • The x:DataType does not match the actual DataContext type.
  • The property does not exist on the declared data type.

Fix: Verify x:DataType matches your view model. Use a reflection binding to bypass compile-time checking if needed.

<TextBlock Text="{ReflectionBinding DynamicProperty}" />

Method binding overload not resolved​

Symptom: A command bound to an overloaded method fails.

  • Build error reports an unresolved overload when using compiled binding.
  • Runtime binding error reports an unresolved overload when using reflection binding.
  • Runtime exception when the command runs.

Causes:

  • Two or more overloads take one parameter and none takes object, so the choice is ambiguous.
  • Every overload takes two or more parameters, which method binding does not support.
  • The command parameter does not match the method parameter type, when using a compiled binding. (Compiled bindings do not convert CommandParameter.)

Fix: Remove competing overloads. Or add a new overload taking a single object parameter (which is chosen with higher priority). See Binding directly to a method for the full overload resolution rules.

Converter returns UnsetValue​

Symptom: The binding applies the fallback value instead of the converted result.

Cause: Your IValueConverter.Convert method returns AvaloniaProperty.UnsetValue or BindingOperations.DoNothing.

Fix: Return an actual value or null (which triggers TargetNullValue instead).

Using Avalonia DevTools​

Press F12 in the running app to open Avalonia DevTools. Then, use the Elements tool to examine the control's properties, or navigate the logical tree to verify its data context.

Debugging bindings in code​

Observing binding values​

Use GetObservable to watch value changes of a property in real time:

myTextBlock.GetObservable(TextBlock.TextProperty).Subscribe(value =>
{
    Debug.WriteLine($"TextBlock.Text changed to: {value}");
});

Checking the binding source​

// Check what DataContext a control has
Debug.WriteLine($"DataContext type: {myControl.DataContext?.GetType().Name}");
Debug.WriteLine($"DataContext value: {myControl.DataContext}");

Using FallbackValue for diagnostics​

Temporarily add a FallbackValue to identify whether the binding path is failing:

<TextBlock Text="{Binding UserName, FallbackValue='BINDING FAILED'}" />

If you see "BINDING FAILED" in the UI, the binding path is wrong or the data context is null.

Compiled bindings diagnostics​

Compiled bindings are validated at compile time. If a binding path is invalid, you get a build error instead of a silent runtime failure.

You have two options to resolve an invalid compiled binding:

  1. Fix the x:DataType declaration to match the actual data type.
  2. Use ReflectionBinding for dynamic properties that cannot be statically resolved.

Diagnostic checklist​

When a binding does not work:

  1. Check the Output window for binding error messages.
  2. Open DevTools to verify the control's data context.
  3. Verify the property name matches exactly (case-sensitive).
  4. Verify the property is public with a get accessor.
  5. For TwoWay bindings, verify the property has a set accessor and the source implements INotifyPropertyChanged.
  6. Check that the DataContext is set before the binding is evaluated.
  7. Add a FallbackValue to confirm whether the path resolution is the problem.
  8. For compiled bindings, verify x:DataType matches the actual runtime type.

See also​

On this page