dotnet/AspNetCore.Docs · error · Error

`selector` option must be specified when initializing ${this

Error message

`selector` option must be specified when initializing ${this.type} on the window.document object!

What it means

Bootstrap 3's Tooltip.init throws when the target element is a `document` instance and no `selector` option is provided. Delegated tooltips on the document need a selector to know which descendants trigger them; a direct document tooltip would fire for every element.

Source

Thrown at aspnetcore/mvc/views/tag-helpers/th-components/samples/RazorPagesSample/wwwroot/lib/bootstrap/js/bootstrap.js:1314

    delay: 0,
    html: false,
    container: false,
    viewport: {
      selector: 'body',
      padding: 0
    }
  }

  Tooltip.prototype.init = function (type, element, options) {
    this.enabled   = true
    this.type      = type
    this.$element  = $(element)
    this.options   = this.getOptions(options)
    this.$viewport = this.options.viewport && $($.isFunction(this.options.viewport) ? this.options.viewport.call(this, this.$element) : (this.options.viewport.selector || this.options.viewport))
    this.inState   = { click: false, hover: false, focus: false }

    if (this.$element[0] instanceof document.constructor && !this.options.selector) {
      throw new Error('`selector` option must be specified when initializing ' + this.type + ' on the window.document object!')
    }

    var triggers = this.options.trigger.split(' ')

    for (var i = triggers.length; i--;) {
      var trigger = triggers[i]

      if (trigger == 'click') {
        this.$element.on('click.' + this.type, this.options.selector, $.proxy(this.toggle, this))
      } else if (trigger != 'manual') {
        var eventIn  = trigger == 'hover' ? 'mouseenter' : 'focusin'
        var eventOut = trigger == 'hover' ? 'mouseleave' : 'focusout'

        this.$element.on(eventIn  + '.' + this.type, this.options.selector, $.proxy(this.enter, this))
        this.$element.on(eventOut + '.' + this.type, this.options.selector, $.proxy(this.leave, this))
      }
    }

View on GitHub (pinned to c67a80103a)

Solutions

1. Add a `selector` option that matches the trigger elements: `$(document).tooltip({ selector: '[data-toggle="tooltip"]' })`.
2. Bind to a real container element instead of document when possible.
3. Attach tooltips to the specific elements that should show them rather than delegating from document.

Example fix

// before
$(document).tooltip({ placement: 'top' });

// after
$(document).tooltip({ selector: '[data-toggle="tooltip"]', placement: 'top' });

function safeTooltip($elem, opts) {
  if ($elem[0] instanceof document.constructor && !opts.selector) {
    throw new Error('Tooltip on document requires a selector option');
  }
  $elem.tooltip(opts);
}

function isDelegatedTooltipTarget($elem, opts) {
  return !($elem[0] instanceof document.constructor) || typeof opts.selector === 'string';
}

try {
  $(document).tooltip(options);
} catch (e) {
  if (/selector/.test(e.message)) {
    $(document).tooltip(Object.assign({ selector: '[data-toggle="tooltip"]' }, options));
  } else throw e;
}

When it happens

Trigger: Calling `$(document).tooltip({...})` (or similar on a document node) without a `selector` option. Triggered during component initialization.

Common situations: Trying to attach a tooltip to the whole document for global help text; dynamically generated content where the developer bound to document intending delegation but forgot the selector; copy-paste of `$(elem).tooltip()` where elem resolved to document.

Related errors

• ${this.type} `template` option must consist of exactly 1 top
• `selector` option must be specified when initializing ${this
• ${this.type} `template` option must consist of exactly 1 top
• ${this.type} `template` option must consist of exactly 1 top
• Popover requires tooltip.js

AI-assisted analysis of dotnet/AspNetCore.Docs@c67a80103a (2026-08-13). Data as JSON: /api/errors/1270cc60fb347141. Report an issue: GitHub.