MahApps/MahApps.Metro · error · Exception

ButtonsListView is not defined yet. Please use ItemsSource i

Error message

ButtonsListView is not defined yet. Please use ItemsSource instead.

What it means

Thrown by the HamburgerMenu.Items getter when buttonsListView is null. ButtonsListView is the template part resolved in OnApplyTemplate via GetTemplateChild("ButtonsListView"); null means the ControlTemplate lacks that part or Items was accessed before the template applied. The message points to ItemsSource, which works without the template part.

Source

Thrown at src/MahApps.Metro/Controls/HamburgerMenu/HamburgerMenu.Properties.cs:572

        public Style? ItemFocusVisualStyle
        {
            get => (Style?)this.GetValue(ItemFocusVisualStyleProperty);
            protected set => this.SetValue(ItemFocusVisualStylePropertyKey, value);
        }

        /// <summary>
        /// Gets the collection used to generate the content of the items list.
        /// </summary>
        /// <exception cref="Exception">
        /// Exception thrown if ButtonsListView is not yet defined.
        /// </exception>
        public ItemCollection Items
        {
            get
            {
                if (this.buttonsListView is null)
                {
                    throw new Exception("ButtonsListView is not defined yet. Please use ItemsSource instead.");
                }

                return this.buttonsListView.Items;
            }
        }

        /// <summary>
        /// Executes the <see cref="ItemCommand"/>.
        /// </summary>
        public void RaiseItemCommand()
        {
            var command = this.ItemCommand;
            var commandParameter = this.ItemCommandParameter ?? this;
            if (command != null && command.CanExecute(commandParameter))
            {
                command.Execute(commandParameter);
            }
        }

View on GitHub (pinned to 72099e310b)

Solutions

Use the ItemsSource property (bind in XAML) instead of the Items collection.
Ensure the HamburgerMenu ControlTemplate declares a ListBox named 'ButtonsListView'.
Access Items only after the control's Loaded event.
Use the default HamburgerMenu template.

Example fix

<!-- before: code-behind menu.Items.Add(...) before template applied -->

<!-- after: bind the source -->
<controls:HamburgerMenu ItemsSource="{Binding MenuItems}" />

Defensive patterns

Strategy: validation

Validate before calling

// Prefer ItemsSource binding; only read Items after Loaded.
if (menu.IsLoaded)
{
    var items = menu.Items; // safe after template applied
}
// In XAML: ItemsSource="{Binding ...}"

Type guard

static bool HasButtonsListView(HamburgerMenu m)
    => m.IsLoaded && m.Template.FindName("ButtonsListView", m) is ListBox;

Try / catch

try { var items = menu.Items; }
catch (Exception ex) when (ex.Message.Contains("ButtonsListView is not defined"))
{
    // Template missing the part; switch to ItemsSource binding.
}

Prevention

Bind ItemsSource in XAML rather than touching Items in code.
Ensure the HamburgerMenu ControlTemplate includes a ListBox named 'ButtonsListView'.
Access Items only after Loaded.

When it happens

Trigger: Custom HamburgerMenu ControlTemplate missing a ListBox named 'ButtonsListView'; accessing Items in the constructor or before Loaded; design-time/code-gen access to Items.

Common situations: Heavily customized hamburger template that removed the main list view; accessing Items during InitializeComponent; using Items.Add in code before the template is live.

Related errors

AI-assisted analysis of MahApps/MahApps.Metro@72099e310b (2026-08-13). Data as JSON: /api/errors/82014b2c6f2f1389. Report an issue: GitHub.