Troubleshooting & Common Errors
7 questions foundUsually the BindingContext is null/wrong, the path has a typo, or the source doesn't raise PropertyChanged. Enable binding diagnostics/debug output, add x:DataType for compile-time checking, verify BindingContext, and confirm the property raises change notification. FallbackValue helps confirm the binding is evaluated.
<Label Text="{Binding Title, FallbackValue='NO BINDING'}" />
<!-- If 'NO BINDING' shows, the path/context is wrong -->
Real-world example A blank label is traced to a mistyped property name, caught instantly after enabling compiled bindings.
Common follow-ups: How does x:DataType help here? | What does FallbackValue reveal?
Data Binding & MVVM Debugging Troubleshooting & Common Errors
Release enables trimming/AOT, which can strip types used via reflection (JSON models, DI by reflection, XAML resolved dynamically). Fix by using source generators, [DynamicDependency]/[DynamicallyAccessedMembers], TrimmerRootAssembly, or disabling trimming for the assembly. Reproduce with a Release build and read the native crash log.
<ItemGroup>
<TrimmerRootAssembly Include="MyApp.Models" />
</ItemGroup>
Real-world example A Release-only crash deserializing a model is fixed by rooting the models assembly so trimming keeps its members.
Common follow-ups: Why only in Release? | How do you preserve reflected types?
Trimming Deployment Troubleshooting & Common Errors
Increase the Java max heap for the Android build (JavaMaximumHeapSize), enable D8/R8 and resource shrinking, disable multidex issues, and ensure you're not bundling excessive assets. For large apps, enable AndroidLinkMode and reduce ABIs during debug to speed and lighten builds.
<PropertyGroup>
<JavaMaximumHeapSize>2G</JavaMaximumHeapSize>
<AndroidEnableMultiDex>true</AndroidEnableMultiDex>
</PropertyGroup>
Real-world example A CI Android build stops failing after raising the Java heap size and enabling R8 shrinking.
Common follow-ups: What does R8 do? | Why limit ABIs in debug?
Android Deployment Troubleshooting & Common Errors
The bound collection must be an ObservableCollection (or raise CollectionChanged), and items must raise PropertyChanged for their own field updates. Reassigning a plain List won't refresh unless the holding property notifies. Also ensure updates happen on the UI thread.
// Won't refresh:
Items = new List<Item>(newData);
// Will refresh:
public ObservableCollection<Item> Items { get; } = new();
Items.Clear(); foreach (var i in newData) Items.Add(i);
Real-world example A list that never refreshed is fixed by switching from List to ObservableCollection and mutating it on the UI thread.
Common follow-ups: What interface must the collection implement? | Why must items notify too?
Collections Data Binding & MVVM Troubleshooting & Common Errors
The custom handler isn't registered, or CreatePlatformView returns nothing for a platform. Register handlers in MauiProgram via ConfigureMauiHandlers(h => h.AddHandler(typeof(MyControl), typeof(MyHandler))), and ensure every target platform has an implementation.
builder.ConfigureMauiHandlers(h =>
h.AddHandler(typeof(MyControl), typeof(MyControlHandler)));
Real-world example A blank custom control appears until the team registers its handler in MauiProgram for all platforms.
Common follow-ups: Where do you register handlers? | What if one platform lacks an implementation?
Handlers Custom Controls Troubleshooting & Common Errors
Inspect the visual tree (Live Visual Tree), check HorizontalOptions/VerticalOptions and Fill vs Center, verify parent layout constraints (a StackLayout gives infinite space in its direction), and watch for zero/collapsed sizes. Add temporary background colors to see actual bounds. Prefer Grid for precise control.
<!-- Temporarily visualize bounds -->
<VerticalStackLayout BackgroundColor="Red">
<Label BackgroundColor="Yellow" Text="..." />
</VerticalStackLayout>
Real-world example A clipped label is diagnosed by coloring backgrounds, revealing a parent with a fixed height too small for its content.
Common follow-ups: Why can StackLayout hide sizing bugs? | What does Fill do?
Layouts Debugging Troubleshooting & Common Errors
Verify the App ID, certificate, and provisioning profile match and haven't expired; ensure the bundle identifier is consistent; and that entitlements match the profile. Use automatic provisioning for development and explicit profiles for distribution. Clear stale profiles and re-download from the Apple Developer portal.
Real-world example A signing failure is fixed after regenerating a distribution profile whose entitlements no longer matched the app's capabilities.
Common follow-ups: Dev vs distribution provisioning? | What must match the bundle id?
iOS Deployment Troubleshooting & Common Errors