plotly/plotly.js · error

API call to Plotly.${method} rejected.

Error message

API call to Plotly.${method} rejected.

What it means

Plotly.wrap API commands (Plotly.restyle, Plotly.relayout, etc.) are wrapped so that when the underlying promise rejects, a warning 'API call to Plotly.X rejected.' is logged and the original error is re-thrown via the returned promise. The library logs this to give context that the failure came from a public API entry point; the actual cause is the rejection reason carried along.

Source

Thrown at src/plots/command.js:265

 * @param {string} method
 *      The name of the plotly command to execute. Must be one of 'animate',
 *      'restyle', 'relayout', 'update'.
 * @param {array} args
 *      A list of arguments passed to the API command
 */
exports.executeAPICommand = function(gd, method, args) {
    if(method === 'skip') return Promise.resolve();

    var _method = Registry.apiMethodRegistry[method];
    var allArgs = [gd];
    if(!Array.isArray(args)) args = [];

    for(var i = 0; i < args.length; i++) {
        allArgs.push(args[i]);
    }

    return _method.apply(null, allArgs).catch(function(err) {
        Lib.warn('API call to Plotly.' + method + ' rejected.', err);
        return Promise.reject(err);
    });
};

exports.computeAPICommandBindings = function(gd, method, args) {
    var bindings;

    if(!Array.isArray(args)) args = [];

    switch(method) {
        case 'restyle':
            bindings = computeDataBindings(gd, args);
            break;
        case 'relayout':
            bindings = computeLayoutBindings(gd, args);
            break;
        case 'update':
            bindings = computeDataBindings(gd, [args[0], args[2]])

View on GitHub (pinned to 1d090e0b5f)

Solutions

1. Inspect the second argument of the warning (the rejection reason) — it holds the real error; fix the root cause there.
2. Validate arguments before calling: ensure gd is a div already passed through Plotly.newPlot and that attributes exist in the schema (check test/plot-schema.json or the reference page).
3. Await each API call and handle rejection: wrap the call in try/catch with async/await or .catch to control the failure.
4. If the div can be removed by React/framework unmounting, guard with document.body.contains(gd) before calling.
5. Upgrade plotly.js if the rejection is caused by a fixed upstream bug.

Example fix

// before
Plotly.restyle(gd, 'marker.color', 'not-a-color');
// after
try {
  await Plotly.restyle(gd, 'marker.color', '#ff0000');
} catch (err) {
  console.error('restyle failed:', err); // real cause
}

async function safeRestyle(gd, ...args) {
  if (!gd || !gd.classList || !gd.classList.contains('js-plotly-plot')) {
    throw new Error('gd is not an initialized plotly graph div');
  }
  return Plotly.restyle(gd, ...args);
}

function isGraphDiv(el) {
  return el instanceof HTMLElement && typeof el._fullLayout === 'object' && el._fullLayout !== null;
}

try {
  await Plotly.restyle(gd, update);
} catch (err) {
  console.warn('Plotly API call rejected:', err); // err is the root cause logged by the wrapper
}

When it happens

Trigger: Any call to a wrapped Plotly API method (e.g. Plotly.restyle(gd, 'x', [[bad]]), Plotly.relayout, Plotly.addTraces, Plotly.animate) whose internal promise rejects — typically invalid arguments, a missing/unresponsive graph div, or an error thrown inside a reactive plotting step.

Common situations: Passing a non-DOM element or detached div as gd; invalid trace/attribute values caught during Plots.react; calling Plotly.newPlot on a container that was removed from the document mid-call; promise rejection from Plotly.purge-then-call sequences.

Related errors

• animate failure: frame not found: "${frameName}"
• unrecognized GUI edit: ${key}
• unrecognized GUI edit: ${key} in trace uid ${uid}
• addFrames: overwriting frame "${name}" with a frame whose na
• addFrames: This API call has yielded too many of these warni

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