pentaho/pentaho-kettle · error · Error

is already included.

Error message

${elemWithKey} is already included.

What it means

Collection._adding throws this when an element being added casts to a valid element whose key already exists in the collection. Keyed collections enforce key uniqueness, so adding a second element with an identical key is rejected at insertion time via this Error. The message includes a human-readable description of the offending element (produced by _sayElemWithKey).

Solutions

1. De-duplicate the input array before passing it to add/addN or the collection constructor
2. Check collection.has(key) with the element's key before adding
3. Remove the existing element first (collection.remove(key)) if replacement was intended
4. If the key is computed (e.g. from a name property), rename one of the colliding elements

Example fix

// before
list.add({name: 'x'}); // twice -> throws
// after
if (!list.has('x')) list.add({name: 'x'});

function canAdd(list, elem) {
  var key = elem && elem.name;
  return key != null && !list.has(key);
}
if (canAdd(list, elem)) list.add(elem);

function hasUniqueKey(list, elem) {
  return elem != null && elem.name != null && !list.has(elem.name);
}

try {
  list.add(elem);
} catch (e) {
  if (String(e.message).indexOf('is already included') >= 0) {
    list.remove(elem.name);
    list.add(elem);
  } else throw e;
}

When it happens

Trigger: Calling add/addN/addF or collection-constructor element arrays (anything that routes through _adding) with an element whose _getElemKey value equals an existing element's key. Also triggered by replaceAt/_replacing casts when the replacement resolves to a duplicate key.

Common situations: Adding the same specification item, filter, or visual role twice in pentaho component/Model config; duplicate entries in a declarative array (e.g. two `select` fields with the same name); merging configs where both base and extension define the same keyed element.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

• Key already added [key= ]
• A module with the id or alias
• Duplicate parameter ' ' detected.
• is not defined.

AI-assisted analysis of pentaho/pentaho-kettle@f3058517a1 (2026-09-13). Data as JSON: /api/errors/7790edbd9aa9368f. Report an issue: GitHub.

Appendix: source

Thrown at plugins/core-ui/src/main/resources/app/pentaho/lang/Collection.js:118

    _getElemKey: function(elem) {
      return elem.key;
    },

    _sayElemWithKey: function(key) {
      return "A " + this._getElemName() + " with " + this._getKeyName() + " '" + key + "'";
    },

    _sayElemCannotHaveNullyKey: function() {
      return "A " + this._getElemName() + " cannot have a nully " + this._getKeyName() + " value.";
    },

    _adding: function(elem, index, ka) {
      var elem2 = this._cast(elem, index, ka);
      if(elem2 !== undefined) {
        var key = this._getElemKey(elem2);
        if(key == null) throw new Error(this._sayElemCannotHaveNullyKey());
        if(this.has(key)) throw new Error(this._sayElemWithKey(key) + " is already included.");
      }

      return elem2;
    },

    _replacing: function(elem, index, elem0, ka) {
      var elem2 = this._cast(elem, index, ka);
      if(elem2 !== undefined) {
        var key = this._getElemKey(elem2);
        if(key == null) throw new Error(this._sayElemCannotHaveNullyKey());
      }

      return elem2;
    },

    _added: function(elem) {
      this.__keys[this._getElemKey(elem)] = elem;
    },

View on GitHub (pinned to f3058517a1)