stride3d/stride · error · InvalidOperationException

The content of an ImageButton cannot be modified by the…

Error message

The content of an ImageButton cannot be modified by the user.

What it means

ImageButton derives its Content automatically from its pressed/not-pressed state, rendered from Button.PressedImage and Button.NotPressedImage. Because the content is state-driven, the library forbids assigning it manually and the Content setter unconditionally throws InvalidOperationException. Setting the visuals must be done through the image properties.

Solutions

Set Button.PressedImage and Button.NotPressedImage instead of Content
If arbitrary content is needed, use a regular Button or ToggleButton rather than ImageButton
Remove the Content element from serialized UI assets for ImageButton nodes
Wrap custom visuals into images/sprites if ImageButton is required

Example fix

// before
var imgBtn = new ImageButton();
imgBtn.Content = new TextBlock { Text = "OK" }; // throws
// after
var imgBtn = new ImageButton();
imgBtn.NotPressedImage = notPressedSprite;
imgBtn.PressedImage = pressedSprite;

Defensive patterns

Strategy: type-guard

Validate before calling

if (element is ImageButton)
    throw new NotSupportedException("Set PressedImage/NotPressedImage instead of Content");

Type guard

bool CanSetContent(UIElement e) => e is not ImageButton;

Try / catch

try
{
    button.Content = child;
}
catch (InvalidOperationException ex) when (ex.Message.Contains("ImageButton"))
{
    // fall back to setting images on the ImageButton
}

Prevention

Set ImageButton visuals via PressedImage/NotPressedImage only
Use plain Button when custom content is required
Audit serialized UI assets for Content nodes under ImageButton

When it happens

Trigger: Any code that assigns content to an ImageButton, e.g. imageButton.Content = someUIElement; or via XAML/yaml serialization setting a Content node on an ImageButton; generic UI-building code that sets Content on any Button subclass.

Common situations: Refactoring a Button into an ImageButton while keeping Content assignments; copy-pasted UI construction code; designers converting scene assets where a Content block remains under the ImageButton node.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

AI-assisted analysis of stride3d/stride@96fad776d2 (2026-09-14). Data as JSON: /api/errors/deaad4d4a53f73d1. Report an issue: GitHub.

Appendix: source

Thrown at sources/engine/Stride.UI/Controls/ImageButton.cs:47

        {
            UpdateContentImage();
        }

        private void UpdateContentImage()
        {
            contentImageElement.Source = ButtonImageProvider;
        }

        /// <summary>
        /// The current content of the <see cref="ImageButton"/>, that is the current image used.
        /// </summary>
        /// <remarks>The <see cref="Content"/> of a <see cref="ImageButton"/> is determined by its state (pressed/not pressed) and the value of
        /// <see cref="Button.PressedImage"/> and <see cref="Button.NotPressedImage"/>. 
        /// The <see cref="Content"/> cannot be set manually by the user.</remarks>
        /// <exception cref="InvalidOperationException">The user tried to modify the <see cref="ImageButton"/> content.</exception>
        public override UIElement Content
        {
            set { throw new InvalidOperationException("The content of an ImageButton cannot be modified by the user."); }
        }

        public override bool IsPressed
        {
            get { return base.IsPressed; }
            protected set
            {
                if (value == IsPressed)
                    return;

                base.IsPressed = value;

                UpdateContentImage();
            }
        }

        private class ImageButtonMetadata
        {

View on GitHub (pinned to 96fad776d2)