handlebars-lang/handlebars.js · error · Handlebars.Exception

Unable to output multiple templates in simple mode

Error message

Unable to output multiple templates in simple mode

What it means

The precompiler CLI throws when --simple (-s) is used but more than one template (or a directory of templates) is provided. Simple mode emits exactly one bare template function with no registry, so it can only handle a single named template.

Source

Thrown at lib/precompiler.js:173

export async function cli(opts) {
  if (opts.version) {
    console.log(Handlebars.VERSION);
    return;
  }

  if (!opts.templates.length && !opts.hasDirectory) {
    throw new Handlebars.Exception(
      'Must define at least one template or directory.'
    );
  }

  if (opts.simple && opts.min) {
    throw new Handlebars.Exception('Unable to minimize simple output');
  }

  const multiple = opts.templates.length !== 1 || opts.hasDirectory;
  if (opts.simple && multiple) {
    throw new Handlebars.Exception(
      'Unable to output multiple templates in simple mode'
    );
  }

  // Force simple mode if we have only one template and it's unnamed.
  if (opts.templates.length === 1 && !opts.templates[0].name) {
    opts.simple = true;
  }

  // Convert the known list into a hash
  let known = {};
  if (opts.known && !Array.isArray(opts.known)) {
    opts.known = [opts.known];
  }
  if (opts.known) {
    for (let i = 0, len = opts.known.length; i < len; i++) {
      known[opts.known[i]] = true;
    }

View on GitHub (pinned to 13a7a67991)

Solutions

1. Compile a single template file with -s, one output per template
2. Drop -s so multiple templates compile into the standard registry format
3. Run the CLI once per template with -s and separate -f outputs

Example fix

// before
handlebars -s src/templates/ -f dist/tpl.js

// after
handlebars src/templates/ -f dist/tpl.js
// or simple, one at a time
handlebars -s src/templates/home.hbs -f dist/home.js

const fileCount = (await glob(templatesGlob)).length;
if (flags.simple && fileCount !== 1) {
  throw new Error('--simple supports exactly one template; got ' + fileCount);
}

try {
  execSync(cliCmd);
} catch (e) {
  if (/multiple templates in simple mode/.test(e.message)) {
    // remove -s or compile one template at a time
  } else throw e;
}

When it happens

Trigger: Running `handlebars -s templates/a.hbs templates/b.hbs` or `handlebars -s templates/` (directory implies multiple).

Common situations: Pointing -s at a whole templates directory; glob expansion passing several files to a simple-mode compile; precompiled multiple files being concatenated later.

Related errors

• Must define at least one template or directory.
• Unable to minimize simple output
• Name missing for template
• Invalid stack pop
• Must pass iterator to #each

AI-assisted analysis of handlebars-lang/handlebars.js@13a7a67991 (2026-09-02). Data as JSON: /api/errors/ffde2824476e0d14. Report an issue: GitHub.