What causes "Unrecognized full object edit value" in plotly/plotly.js?

Use a plain object to set/replace the item: Plotly.relayout(gd, 'annotations[0]', {x: 1, y: 2})

Unrecognized full object edit value

Error message

Unrecognized full object edit value

What it means

manage_arrays.applyContainerArrayChanges edits container arrays (annotations, shapes, etc.) driven by relayout-style update objects. When an entry at a component index sets the whole object (key ''), that value must be an add value ('add' string or a plain object) or a remove value (null / [0]); anything else is unrecognized, so the edit is skipped and this warning is logged.

Source

Thrown at src/plot_api/manage_arrays.js:146

            Loggers.warn('index out of range', componentType, componentNum);
            continue;
        }

        if(objVal !== undefined) {
            if(objKeys.length > 1) {
                Loggers.warn(
                    'Insertion & removal are incompatible with edits to the same index.',
                    componentType, componentNum);
            }

            if(isRemoveVal(objVal)) {
                deletes.push(componentNum);
            } else if(adding) {
                if(objVal === 'add') objVal = {};
                componentArray.splice(componentNum, 0, objVal);
                if(componentArrayFull) componentArrayFull.splice(componentNum, 0, {});
            } else {
                Loggers.warn('Unrecognized full object edit value',
                    componentType, componentNum, objVal);
            }

            if(firstIndexChange === -1) firstIndexChange = componentNum;
        } else {
            for(j = 0; j < objKeys.length; j++) {
                prefix = componentType + '[' + componentNum + '].';
                _nestedProperty(componentArray[componentNum], objKeys[j], prefix)
                    .set(objEdits[objKeys[j]]);
            }
        }
    }

    // now do deletes
    for(i = deletes.length - 1; i >= 0; i--) {
        componentArray.splice(deletes[i], 1);
        // TODO: this drops private keys that had been stored in componentArrayFull
        // does this have any ill effects?

View on GitHub (pinned to 1d090e0b5f)

Solutions

Use a plain object to set/replace the item: Plotly.relayout(gd, 'annotations[0]', {x: 1, y: 2})
Use the literal string 'add' or {} to insert a new item at the index
Use null (or [0]) to remove the item: Plotly.relayout(gd, 'annotations[0]', null)
Validate the value's type before calling relayout; only strings === 'add', plain objects, and null are valid
For bulk edits pass the aobj form Plotly.relayout(gd, {'annotations[0]': {...}}) with correctly typed values

Example fix

// before
Plotly.relayout(gd, 'annotations[0]', 'add annotation');
// after
Plotly.relayout(gd, 'annotations[0]', {text: 'add annotation', x: 0.5, y: 0.5});

Defensive patterns

Strategy: validation

Validate before calling

function isValidWholeObjectEdit(v) {
  return v === 'add' || v === null || (v && typeof v === 'object' && !Array.isArray(v));
}
// check each value before relayout with key '' semantics
if (!isValidWholeObjectEdit(value)) throw new Error('Use an object, \'add\', or null for ' + attr);

Type guard

function isPlainObj(v) { return v !== null && typeof v === 'object' && !Array.isArray(v); }
const isAdd = v => v === 'add' || isPlainObj(v);
const isRemove = v => v === null;

Prevention

Only use 'add', a plain object, or null for whole-container-index relayout values
Never invent removal keywords; plotly.js removal is null or [0]
Type-check dynamically built update objects before calling relayout
Prefer the {attr: value} aobj form so you can validate all values at once

When it happens

Trigger: Calling Plotly.relayout/Plotly.update with a whole-object assignment whose value is not 'add', not a plain object, and not a removal value, e.g. Plotly.relayout(gd, 'annotations[0]', 'mystery') or Plotly.relayout(gd, 'shapes[1]', 42).

Common situations: Typos like 'removed' instead of null; passing a number/string where an annotation object was intended; serializing updates through a backend that turned null into the string 'null'; older code using legacy removal values that newer plotly.js no longer accepts.

Related errors

AI-assisted analysis of plotly/plotly.js@1d090e0b5f (2026-09-02). Data as JSON: /api/errors/707d8bcd7c298a37. Report an issue: GitHub.