cefsharp/CefSharp · error · Exception

invalid or illegal characters used for binding property name

Error message

invalid or illegal characters used for binding property names. Alphanumeric and underscores characters only.

What it means

Thrown by the JavascriptBindingApiGlobalObjectName setter when the proposed name fails StringCheck.IsLettersAndNumbers, which requires a non-empty/non-whitespace string matching ^\w+$ (letters, digits, underscore only). This name becomes a global/window property in JavaScript, so it must be a valid identifier without dots, dashes, spaces, or symbols.

Source

Thrown at CefSharp/JavascriptBinding/JavascriptBindingSettings.cs:88

        /// be created e.g. cefSharp.bindObjectAsync, CefSharp.BindObjectAsync.
        /// If specified then your custom name will be used, if the name starts with a lowercase letter
        /// then all the functions will be lowercase, e.g. myObjName.bindObjectAsync otherwise
        /// the functions will start with a uppercase letter e.g. MyObjName.BindObjectAsync
        /// </summary>
        /// <remarks>
        /// This object is also accessible through the window property. e.g. window.cefSharp.bindObjectAsync
        /// </remarks>
        public string JavascriptBindingApiGlobalObjectName
        {
            get { return jsBindingGlobalObjectName; }
            set
            {
                ThrowIfFrozen();

                if (!StringCheck.IsLettersAndNumbers(value))
                {
                    //TODO: See if there's a better suited Exception class for this.
                    throw new System.Exception("invalid or illegal characters used for binding property names. Alphanumeric and underscores characters only.");
                }

                jsBindingGlobalObjectName = value;
            }
        }

        /// <summary>
        /// Objects registered using <see cref="IJavascriptObjectRepository.Register"/>
        /// will be automatically bound when a V8Context is created. (Soon as the Javascript
        /// context is created for a browser). This behaviour is like that seen with Javascript
        /// Binding in version 57 and earlier.
        /// </summary>
        public bool LegacyBindingEnabled
        {
            get { return legacyBindingEnabled; }
            set
            {
                ThrowIfFrozen();

View on GitHub (pinned to 16bc6e0711)

Solutions

1. Use a single alphanumeric/underscore identifier (e.g. 'cefSharp', 'myApp').
2. Validate the value with a ^\w+$ check before assigning.
3. Call ThrowIfFrozen-style guards earlier if the settings are already in use.
4. Keep the default if you do not need a custom global name.

Example fix

// before
settings.JavascriptBindingApiGlobalObjectName = "my.api"; // dot not allowed

// after
settings.JavascriptBindingApiGlobalObjectName = "myApi";

static bool IsValidGlobalName(string s) =>
    !string.IsNullOrWhiteSpace(s) && System.Text.RegularExpressions.Regex.IsMatch(s, @"^\w+$");
if (IsValidGlobalName(name)) settings.JavascriptBindingApiGlobalObjectName = name;

static bool IsValidGlobalName(string s) =>
    !string.IsNullOrWhiteSpace(s) && System.Text.RegularExpressions.Regex.IsMatch(s, @"^\w+$");

try { settings.JavascriptBindingApiGlobalObjectName = name; }
catch (Exception ex) when (ex.Message.Contains("invalid or illegal characters"))
{ settings.JavascriptBindingApiGlobalObjectName = "cefSharp"; /* fallback */ }

When it happens

Trigger: Setting JavascriptBindingApiGlobalObjectName to a value containing dots (e.g. 'my.api'), dashes, spaces, a path, an empty string, or null.

Common situations: Trying to namespace the global object with a dotted path; copying a name from a URL or config with disallowed characters; passing whitespace by accident.

Related errors

• converter
• name
• value
• To enable synchronous JS bindings set WcfEnabled true in Cef
• Object already bound with name:{name}

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