{"record":{"id":"9e9cc707c1aefc99","repo":"handlebars-lang/handlebars.js","slug":"invalid-stack-pop","errorCode":null,"errorMessage":"Invalid stack pop","messagePattern":"Invalid stack pop","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"lib/handlebars/compiler/javascript-compiler.js","lineNumber":1005,"sourceCode":"        this.compileStack.push(stack);\n      }\n    }\n  },\n  isInline: function () {\n    return this.inlineStack.length;\n  },\n\n  popStack: function (wrapped) {\n    let inline = this.isInline(),\n      item = (inline ? this.inlineStack : this.compileStack).pop();\n\n    if (!wrapped && item instanceof Literal) {\n      return item.value;\n    } else {\n      if (!inline) {\n        /* v8 ignore next */\n        if (!this.stackSlot) {\n          throw new Exception('Invalid stack pop');\n        }\n        this.stackSlot--;\n      }\n      return item;\n    }\n  },\n\n  topStack: function () {\n    let stack = this.isInline() ? this.inlineStack : this.compileStack,\n      item = stack[stack.length - 1];\n\n    /* v8 ignore next */\n    if (item instanceof Literal) {\n      return item.value;\n    } else {\n      return item;\n    }\n  },","sourceCodeStart":987,"sourceCodeEnd":1023,"githubUrl":"https://github.com/handlebars-lang/handlebars.js/blob/13a7a679910d2adbfe7f6fad61ce8f98426b0378/lib/handlebars/compiler/javascript-compiler.js#L987-L1023","documentation":"This error is thrown by the Handlebars JavaScript compiler when a compiled template attempts to pop a value from the internal expression stack that was never pushed. It means the compiler's stackSlot bookkeeping reached zero (or was never initialized) while generating code to reference a stack item, indicating an internal compiler-state inconsistency.","triggerScenarios":"Calling compile/JavaScriptCompiler methods directly with hand-built AST nodes; using internal APIs (compiler.inline, compiler.pop) outside normal template compilation; an AST produced or mutated in ways the compiler didn't expect (e.g. a stackVar/depthed value referenced without a prior push); passing a wrapped item expecting a Literal return path when no push happened.","commonSituations":"Usually only hit when patching Handlebars, writing custom compiler passes/plugins, or upgrading Handlebars while relying on undocumented compiler internals; occasionally seen with mismatched handlebars/parser package versions producing AST nodes the compiler mis-wraps.","solutions":["Do not call JavaScriptCompiler/compiler internals directly; compile templates only via Handlebars.compile / the public compile API.","Align @handlebars/parser and handlebars versions (custom AST passes must match the compiler's expected AST shape).","Check any custom AST transforms for nodes that reference stack variables without a corresponding push.","Upgrade Handlebars to the latest patch release; if it persists, file a minimal reproduction issue.","As a workaround, precompile templates at build time (handlebars CLI) instead of compiling at runtime."],"exampleFix":"// before: poking internals\nconst compiler = new Handlebars.JavaScriptCompiler();\ncompiler.compile([{ }, {op: '_ stack'}, ...]);\n// after: public API\nconst template = Handlebars.compile(source);\nconst html = template(data);","handlingStrategy":"try-catch","validationCode":"// Do not touch compiler internals; guard custom AST passes instead\nif (!Array.isArray(ast.body)) throw new Error('Invalid AST passed to compiler');","typeGuard":"function isSafeAstNode(node) {\n  return node != null && typeof node === 'object' && typeof node.type === 'string';\n}","tryCatchPattern":"try {\n  const template = Handlebars.compile(source);\n  return template(data);\n} catch (e) {\n  if (e && e.message === 'Invalid stack pop') {\n    throw new Error('Template compiler state corrupted; recompile from source and avoid internal APIs');\n  }\n  throw e;\n}","preventionTips":["Only compile via Handlebars.compile/precompile, never via JavaScriptCompiler directly","Keep @handlebars/parser and handlebars versions in lockstep","Avoid hand-mutating the AST before compilation","Precompile templates at build time to surface compiler bugs early","Pin exact versions in CI and re-run template test suites on upgrade"],"tags":["handlebars","compiler-internals","stack-underflow"],"backgroundTag":"handlebars-invalid-stack-pop","analyzedSha":"13a7a679910d2adbfe7f6fad61ce8f98426b0378","analyzedAt":"2026-09-02T20:25:07.518Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-10T02:17:09.455Z"}