What causes "'{invalidTransition}' transition could not be found!" in MahApps/MahApps.Metro?

Set Transition to a value that has a matching VisualState in your template, or use the default MahApps template which defines all standard transitions.

MahApps/MahApps.Metro · error · MahAppsException

'{invalidTransition}' transition could not be found!

Error message

'{invalidTransition}' transition could not be found!

What it means

Thrown by TransitioningContentControl.OnApplyTemplate when GetStoryboard(this.Transition) returns null, meaning the configured Transition does not map to any VisualState storyboard in the applied template. The control reverts Transition to the default and throws a MahAppsException naming the invalid transition. This fires at template-apply time, so it surfaces as soon as the window/control loads.

Source

Thrown at src/MahApps.Metro/Controls/TransitioningContentControl.cs:284

                    }
                }
            }

            base.OnApplyTemplate();

            this.previousContentPresentationSite = this.GetTemplateChild(PreviousContentPresentationSitePartName) as ContentPresenter;
            this.currentContentPresentationSite = this.GetTemplateChild(CurrentContentPresentationSitePartName) as ContentPresenter;

            // hookup currenttransition
            var transition = this.GetStoryboard(this.Transition);
            this.CurrentTransition = transition;
            if (transition is null)
            {
                var invalidTransition = this.Transition;
                // revert to default
                this.Transition = DefaultTransitionState;

                throw new MahAppsException($"'{invalidTransition}' transition could not be found!");
            }

            VisualStateManager.GoToState(this, HiddenState, false);
        }

        protected override void OnContentChanged(object oldContent, object newContent)
        {
            base.OnContentChanged(oldContent, newContent);

            if (oldContent != newContent)
            {
                this.StartTransition(oldContent, newContent);
            }
        }

        [SuppressMessage("Microsoft.Usage", "CA1801:ReviewUnusedParameters", MessageId = "newContent", Justification = "Should be used in the future.")]
        private void StartTransition(object oldContent, object newContent)
        {

View on GitHub (pinned to 72099e310b)

Solutions

Set Transition to a value that has a matching VisualState in your template, or use the default MahApps template which defines all standard transitions.
If using a custom template, copy the full set of transition VisualStates from MahApps' default TransitioningContentControl style.
After an upgrade, review release notes for renamed TransitionType members.

Example fix

<!-- before -->
<controls:TransitioningContentControl Transition="CustomTransition"/>
<!-- 'CustomTransition' VisualState missing in template -->

<!-- after: use a standard transition defined in default template -->
<controls:TransitioningContentControl Transition="RightTransition"/>

Defensive patterns

Strategy: try-catch

Validate before calling

// Verify the storyboard resolves before relying on the transition
var sb = tcc.GetStoryboard(desiredTransition);
if (sb == null)
    throw new InvalidOperationException($"No storyboard for transition '{desiredTransition}'");
tcc.Transition = desiredTransition;

Try / catch

try
{
    tcc.ApplyTemplate();
}
catch (MahAppsException ex) when (ex.Message.Contains("transition could not be found"))
{
    // the set Transition has no VisualState; revert to default
    tcc.Transition = TransitioningContentControl.DefaultTransitionState;
}

Prevention

Use the default MahApps TransitioningContentControl template which defines all standard transitions.
When customizing, include a VisualState for every TransitionType you may set.
Set Transition after confirming the template is applied to catch errors at a known point.

When it happens

Trigger: The Transition property is set to a value whose VisualState is not defined in the ControlTemplate's VisualStateManager. Distinct from error 57: this fires in OnApplyTemplate (startup) whereas 57 fires in the property-changed callback. Both have the same root cause (missing transition state).

Common situations: Custom ControlTemplate for TransitioningContentControl omits the VisualState for the set Transition. Using a non-default Transition without the corresponding style. Version upgrade where transition names changed.

Related errors

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