dotnet/wpf · error · InvalidOperationException

An error occurred while mapping a property.

Error message

An error occurred while mapping a property.

What it means

RunTranslator wraps the execution of a PropertyTranslator; when the translator delegate throws, PropertyMap raises the PropertyMappingError event and, if PropertyMappingExceptionEventArgs.ThrowException is true, rethrows as an InvalidOperationException with inner exception 'ex'. This lets hosts decide whether a mapping failure should crash or be logged.

Solutions

1. Read the InnerException to find the real failure inside the translator delegate.
2. Fix the translator's logic (type casts, null checks) so it does not throw.
3. Subscribe to the PropertyMappingError event to log/instead of throwing; do not set args.ThrowException = true.
4. Validate the property value type before the translator uses it.

Example fix

// before
propertyMap.Add("Background", (o, e) => ((System.Windows.Controls.Control)o).Background = (System.Windows.Media.Brush)e.Value); // bad cast
// after
propertyMap.Add("Background", (o, e) =>
{
    var ctl = o as System.Windows.Controls.Control;
    if (ctl != null && e.Value is System.Windows.Media.Brush brush)
        ctl.Background = brush;
});

propertyMap.PropertyMappingError += (s, e) => { log.Error($"Mapping failed for {e.PropertyName}", e.Exception); e.ThrowException = false; };

try { propertyMap.Apply(); }
catch (InvalidOperationException ex) when (ex.InnerException != null)
{ log.Error("Property translation failed", ex.InnerException); }

When it happens

Trigger: A custom PropertyTranslator added via propertyMap.Add(...) throws inside its delegate (e.g. casting the property value to the wrong type), and either the default behavior or an event handler sets ThrowException = true.

Common situations: Custom translators written for one control type applied to another; translator code assuming a non-null SourceObject or specific value type; exceptions in translators triggered during layout when WindowsFormsHost applies mappings.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• ' ' name is already in use.
• Animation_Exception
• Animation_Invalid_DefaultValue
• Argument 'propertyName' cannot be null or empty.
• Cannot remove signature from read-only file.

AI-assisted analysis of dotnet/wpf@81131a70a4 (2026-09-14). Data as JSON: /api/errors/f2afa2d91cab4aab. Report an issue: GitHub.

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/WindowsFormsIntegration/System/Windows/Integration/PropertyMap.cs:320

        //In this specific case, we are catching the exception and firing an event which can be handled in user code
        //The user handling the event can make the determination on whether or not the exception should be rethrown
        //(Wrapped in an InvalidOperationException).
        internal void RunTranslator(PropertyTranslator translator, object host, string propertyName, object value)
        {
            try
            {
                translator(host, propertyName, value);
            }
            catch (Exception ex)
            {
                PropertyMappingExceptionEventArgs args = new PropertyMappingExceptionEventArgs(ex, propertyName, value);
                if (_propertyMappingError != null)
                {
                    _propertyMappingError(SourceObject, args);
                }
                if (args.ThrowException)
                {
                    throw new InvalidOperationException(SR.WFI_PropertyMapError, ex);
                }
            }
        }

        private event EventHandler<PropertyMappingExceptionEventArgs> _propertyMappingError;

        /// <summary>
        /// Occurs when an exception is raised by a PropertyMap delegate.
        /// </summary>
        public event EventHandler<PropertyMappingExceptionEventArgs> PropertyMappingError
        {
            add { _propertyMappingError += value; }
            remove { _propertyMappingError -= value; }
        }
    }
}

View on GitHub (pinned to 81131a70a4)