apache/hadoop · error · Error

{} `template` option must consist of exactly 1 top-level ele

Error message

{} `template` option must consist of exactly 1 top-level element!

What it means

Tooltip.prototype.tip lazily builds the DOM node from options.template via $(this.options.template) and requires the resulting set to contain exactly one element: this.$tip.length != 1 throws this.type + ' `template` option must consist of exactly 1 top-level element!'. Templates with two or more top-level nodes, only text, or an empty string all fail.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/webapps/static/bootstrap-3.4.1/js/bootstrap.js:1873

    var o  = this.options

    title = $e.attr('data-original-title')
      || (typeof o.title == 'function' ? o.title.call($e[0]) :  o.title)

    return title
  }

  Tooltip.prototype.getUID = function (prefix) {
    do prefix += ~~(Math.random() * 1000000)
    while (document.getElementById(prefix))
    return prefix
  }

  Tooltip.prototype.tip = function () {
    if (!this.$tip) {
      this.$tip = $(this.options.template)
      if (this.$tip.length != 1) {
        throw new Error(this.type + ' `template` option must consist of exactly 1 top-level element!')
      }
    }
    return this.$tip
  }

  Tooltip.prototype.arrow = function () {
    return (this.$arrow = this.$arrow || this.tip().find('.tooltip-arrow'))
  }

  Tooltip.prototype.enable = function () {
    this.enabled = true
  }

  Tooltip.prototype.disable = function () {
    this.enabled = false
  }

  Tooltip.prototype.toggleEnabled = function () {

View on GitHub (pinned to 2add963021)

Solutions

Keep exactly one root element: template: '<div class="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>'
Do not set template at all — the Bootstrap default already satisfies the single-root rule
When composing templates dynamically, wrap the output in a single <div> before assigning it

Example fix

// before
$el.tooltip({template: '<div class="tooltip"></div><div class="extra"></div>'});

// after
$el.tooltip({template: '<div class="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>'});

Defensive patterns

Strategy: validation

Validate before calling

var tpl = '<div class="tooltip"><div class="tooltip-inner"></div></div>';
if ($(tpl).length !== 1) {
  throw new Error('template must have exactly one root element');
}
$el.tooltip({template: tpl});

Prevention

Keep custom templates single-rooted
Omit template to use the tested Bootstrap default
When composing templates dynamically, wrap output in one <div>

When it happens

Trigger: Overriding the tooltip/popover template with markup whose top level has 0 or 2+ elements — e.g. '<div>...</div><div>...</div>', a bare text fragment, or a template string built by concatenation that accidentally produces two roots or is empty.

Common situations: Custom-styled tooltips in HDFS web UI pages; dynamically generated template strings; trimming whitespace/markup in a way that drops the single root element.

Related errors

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/5a1d5ee969a4d399. Report an issue: GitHub.