{"record":{"id":"b95b862ac9afc770","repo":"amark/gun","slug":"tag-name-is-missing-hierarchy-definition","errorCode":null,"errorMessage":"tag \"${name}\" is missing hierarchy definition","messagePattern":"tag \"(.+?)\" is missing hierarchy definition","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/normalize.js","lineNumber":101,"sourceCode":"  }\n\n  function stateMachine() {\n    if(unstableList.length===0)\n      return;\n    var a, i = -1;\n    while (a = unstableList.pop()) { // PERF: running index is probably faster than shift (mutates array)\n      a.unstable = false;\n      $(a.opt.mutate).each(function(i,fn){\n        return fn && fn(a, addUnstable);\n      });\n    }\n  }\n\n  function prepareOptTags(opt) {\n    var name, tag, tags = opt.tags;\n    for(name in tags) {\n      if(opt.hierarchy.indexOf(name)===-1)\n        throw Error('tag \"'+name+'\" is missing hierarchy definition');\n    }\n    opt.hierarchy.forEach(function(name){\n      if(!tags[name]){\n        tags[name] = {attrs: opt.attrs};\n      }\n      (tag=tags[name]).attrs = $.extend(tag.attrs||{}, opt.attrs);\n      tag.name = name; // not used, debug help (REMOVE later?)\n      // order\n      tag.order = opt.hierarchy.indexOf(name)\n      if(tag.order === -1) {\n      throw Error(\"Order of '\"+name+\"' not defined in hierarchy\");\n    }\n    });\n    return opt;\n  }\n\n  // GENERAL UTILS\n","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/amark/gun/blob/552227599d47ba0493824b7fcf8a00c8cd6404ba/lib/normalize.js#L83-L119","documentation":"prepareOptTags validates custom options passed to $.normalize: every key in opt.tags must also appear in opt.hierarchy. The hierarchy array defines the canonical tag ordering/structure; a tag present in the tags map but absent from the hierarchy has no defined place in the normalization model, so the library refuses to proceed with this error.","triggerScenarios":"Calling $.normalize(html, customOpt) where customOpt (deep-merged over baseOpt) adds a tags entry (e.g. tags: {section: {...}}) without adding 'section' to the hierarchy array. Also triggered by typos in a tag name inside tags that don't match any hierarchy entry.","commonSituations":"Extending the normalizer to support new HTML tags (article, section, figure, custom elements) by only configuring tags; copying a partial customOpt example; deep-extend quirks where $.extend(true, baseOpt, customOpt) merges user tags into the base set while the user's hierarchy list omits base or new tags.","solutions":["Add every tag listed in opt.tags to the opt.hierarchy array, in the desired structural order.","If the tag needs no special config, add it to hierarchy and let prepareOptTags auto-create tags[name] from opt.attrs.","Fix typos so the tags key exactly matches a hierarchy entry.","Merge from baseOpt so the default hierarchy (div, pre, ol, ul, li, h1-h6, p, a, b, code, i, span, s, sub, sup, u, br, img) is preserved and extend, not replace, it.","Validate customOpt before passing: iterate Object.keys(opt.tags) and assert each is in opt.hierarchy."],"exampleFix":"// before\\n$.normalize(html, {tags: {section: {attrs:{}}}});\\n// after\\n$.normalize(html, {hierarchy: ['div','section','p','a','b','i','br','img'], tags: {section: {attrs:{}}}});","handlingStrategy":"validation","validationCode":"function validateNormalizeOpt(opt){\\n  if (!Array.isArray(opt.hierarchy)) throw new Error('opt.hierarchy must be an array');\\n  Object.keys(opt.tags || {}).forEach(function(name){\\n    if (opt.hierarchy.indexOf(name) === -1)\\n      throw new Error('tag \"'+name+'\" must be added to hierarchy');\\n  });\\n}\\n// call validateNormalizeOpt(customOpt) before $.normalize(html, customOpt);","typeGuard":"function optIsConsistent(opt){ return Array.isArray(opt.hierarchy) && !!opt.tags && Object.keys(opt.tags).every(function(n){ return opt.hierarchy.indexOf(n) !== -1; }); }","tryCatchPattern":"try {\\n  validateNormalizeOpt(customOpt);\\n  $.normalize(html, customOpt);\\n} catch (e) {\\n  if (/missing hierarchy definition/.test(e.message)) {\\n    console.error('Config error: add', e.message.match(/tag \"([^\"]+)\"/)[1], 'to hierarchy');\\n  } else { throw e; }\\n}","preventionTips":["Whenever you add a tags entry, add the same tag to hierarchy in the same change.","Extend the base hierarchy rather than replacing it: $.extend(true, {}, baseOpt, customOpt).","Watch for typos — tags keys must exactly equal hierarchy strings.","Write a unit test that runs prepareOptTags-equivalent validation on every shipped option preset."],"tags":["configuration","normalization","hierarchy","options"],"backgroundTag":"missing-hierarchy-definition","analyzedSha":"552227599d47ba0493824b7fcf8a00c8cd6404ba","analyzedAt":"2026-09-02T18:40:58.370Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}