cefsharp/CefSharp · error · ArgumentException

Registering of .Net framework built in types is not supporte

Error message

Registering of .Net framework built in types is not supported, create your own Object and proxy the calls if you need to access a Window/Form/Control.

What it means

Thrown by JavascriptObjectRepository.Register when the value passed in is a .NET framework built-in type. The guard rejects types where type.IsPrimitive is true or whose BaseType namespace starts with "System." (e.g. System.Windows.Forms.Control, System.Windows.Window) because binding framework/CLR types directly is unsupported. The library asks you to wrap such types in your own class and proxy the calls.

Source

Thrown at CefSharp/Internals/JavascriptObjectRepository.cs:242

            if (!CefSharpSettings.WcfEnabled && !isAsync)
            {
                throw new InvalidOperationException(@"To enable synchronous JS bindings set WcfEnabled true in CefSharpSettings before you create
                                                    your ChromiumWebBrowser instances.");
            }            
#endif

            //Validation name is unique
            if (objects.Values.Count(x => string.Equals(x.Name, name, StringComparison.OrdinalIgnoreCase)) > 0)
            {
                throw new ArgumentException("Object already bound with name:" + name, name);
            }

            //Binding of System types is problematic, so we don't support it
            var type = value.GetType();
            if (type.IsPrimitive || type.BaseType.Namespace.StartsWith("System."))
            {
                throw new ArgumentException("Registering of .Net framework built in types is not supported, " +
                    "create your own Object and proxy the calls if you need to access a Window/Form/Control.", "value");
            }

            var jsObject = CreateJavascriptObject(rootObject: true);
            jsObject.Value = value;
            jsObject.Name = name;
            jsObject.JavascriptName = name;
            jsObject.IsAsync = isAsync;
            jsObject.Binder = options?.Binder;
            jsObject.MethodInterceptor = options?.MethodInterceptor;
#if !NETCOREAPP
            jsObject.PropertyInterceptor = options?.PropertyInterceptor;
#endif

            AnalyseObjectForBinding(jsObject, analyseMethods: true, analyseProperties: !isAsync, readPropertyValue: false);
        }

        /// <inheritdoc/>

View on GitHub (pinned to 16bc6e0711)

Solutions

1. Create your own plain class and expose only the methods/properties you need (proxy the underlying control).
2. Register a small DTO/view-model wrapper instead of the framework type.
3. If you only need a primitive value, wrap it in a class with a property that returns the value.
4. Before registering, verify the type is a non-primitive user type whose base is not in the System namespace.

Example fix

// before
repository.Register("form", myWinFormsForm);

// after
public class FormProxy
{
    private readonly Form _form;
    public FormProxy(Form form) => _form = form;
    public void Close() => _form.Close();
    public string Title => _form.Text;
}
repository.Register("form", new FormProxy(myWinFormsForm));

static bool IsBindableType(object value)
{
    var t = value.GetType();
    return !t.IsPrimitive && (t.BaseType == null || !t.BaseType.Namespace.StartsWith("System."));
}
if (IsBindableType(value)) repository.Register(name, value);

static bool IsBindableType(object value)
{
    var t = value.GetType();
    return !t.IsPrimitive && (t.BaseType == null || !t.BaseType.Namespace.StartsWith("System."));
}

try { repository.Register(name, value); }
catch (ArgumentException ex) when (ex.Message.Contains("built in types"))
{ /* wrap in a proxy class and re-register */ }

When it happens

Trigger: Passing a primitive (int, double, bool boxed as object), a System.* derived type, or a WinForms/WPF control (Form, Control, Window) directly to Register. Also note BaseType can be null for System.Object itself, risking a NullReferenceException instead of the documented ArgumentException.

Common situations: Trying to expose a Form or Window to JavaScript for convenience; registering a primitive or a BCL type like System.Collections types; binding a third-party type whose base lives in System.*.

Related errors

• name
• value
• To enable synchronous JS bindings set WcfEnabled true in Cef
• Object already bound with name:{name}
• Method {0} not found on Object of Type {1}

AI-assisted analysis of cefsharp/CefSharp@16bc6e0711 (2026-08-13). Data as JSON: /api/errors/a88a9a33178495c2. Report an issue: GitHub.