plotly/plotly.js · error

Failed to build <trace.type> hierarchy of <trace.name>. Erro

Error message

Failed to build <trace.type> hierarchy of <trace.name>. Error: <e.message>

What it means

src/traces/sunburst/calc.js:139 wraps d3-hierarchy's stratify() in try/catch. If stratify throws — typically because a node's pid references a nonexistent id, or ids are duplicated — Plotly warns 'Failed to build <type> hierarchy' with the underlying error message and aborts building that trace, so it renders empty.

Source

Thrown at src/traces/sunburst/calc.js:139

            }
        }

        cd.unshift({
            hasMultipleRoots: true,
            id: dummyId,
            pid: '',
            label: ''
        });
    }

    // TODO might be better to replace stratify() with our own algorithm
    var root;
    try {
        root = d3Hierarchy.stratify()
            .id(function(d) { return d.id; })
            .parentId(function(d) { return d.pid; })(cd);
    } catch(e) {
        return Lib.warn([
            'Failed to build', trace.type, 'hierarchy of', trace.name + '.',
            'Error:', e.message
        ].join(' '));
    }

    var hierarchy = d3Hierarchy.hierarchy(root);
    var failed = false;

    if(hasValues) {
        switch(trace.branchvalues) {
            case 'remainder':
                hierarchy.sum(function(d) { return d.data.v; });
                break;
            case 'total':
                hierarchy.each(function(d) {
                    var cdi = d.data.data;
                    var v = cdi.v;

View on GitHub (pinned to 1d090e0b5f)

Solutions

1. Verify every parent value matches exactly (string equality, case included) some id in the same trace.
2. Check ids for duplicates and make them unique.
3. Sanitize server-side before plotting: validate the id set contains all parents and fail fast with a clear message.

Example fix

// before
ids: ['a','a1'], parents: ['','root'] // 'root' missing from ids
// after
ids: ['a','a1'], parents: ['','a']

const idSet = new Set(ids);
const orphans = ids.filter((_, i) => parents[i] !== '' && !idSet.has(parents[i]));
const dupes = ids.filter((id, i) => ids.indexOf(id) !== i);
if (orphans.length) throw new Error('Parents not in ids: ' + [...new Set(orphans)]);
if (dupes.length) throw new Error('Duplicate ids: ' + [...new Set(dupes)]);

function hierarchyIsConsistent(ids, parents) {
  const set = new Set(ids);
  if (set.size !== ids.length) return false;
  return parents.every(p => p === '' || set.has(p));
}

try {
  Plotly.newPlot(div, traces);
} catch (e) {
  if (/hierarchy/i.test(e.message)) sanitizeHierarchyData(trace); // fix orphan/duplicate ids then retry
  else throw e;
}

When it happens

Trigger: ids/parents arrays where a parent id has no matching entry in ids (orphan reference), duplicate id values, or pid values that don't resolve, causing d3.stratify to throw during hierarchy construction.

Common situations: Data generated from databases with foreign keys pointing to filtered-out rows; typos or case mismatches between parent and id strings; pagination dropping a parent row while keeping its children.

Related errors

• Multiple implied roots, cannot build <trace.type> hierarchy
• Total value for node <d.data.data.id> of <trace.name> is sma

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