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

Must define at least one template or directory.

Error message

Must define at least one template or directory.

What it means

The handlebars precompiler CLI throws when neither template file arguments nor a directory (-d flag or directory arguments) is supplied — there is nothing to compile. opts.templates is empty and opts.hasDirectory is false.

Source

Thrown at lib/precompiler.js:162

    },
    function (err) {
      if (err) {
        callback(err);
      } else {
        callback(undefined, ret);
      }
    }
  );
}

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;

View on GitHub (pinned to 13a7a67991)

Solutions

1. Pass template paths: handlebars templates/ -f compiled.js
2. Fix the npm script so the glob/path arguments are actually expanded and non-empty
3. In CI, ensure the variable holding template paths is not empty before invoking

Example fix

// before (package.json)
"build:tpl": "handlebars -f dist/templates.js"

// after
"build:tpl": "handlebars src/templates/ -f dist/templates.js"

const tplArgs = args.filter(a => !a.startsWith('-'));
if (tplArgs.length === 0) {
  throw new Error('handlebars CLI requires at least one template path or directory');
}

try {
  execSync('handlebars ...');
} catch (e) {
  if (/Must define at least one template/.test(e.message)) {
    // check that template paths/glob variables were expanded and non-empty
  } else throw e;
}

When it happens

Trigger: Running `handlebars` with no arguments, or with only flags like -f out.js but no template paths/directories.

Common situations: NPM script misconfigured (missing glob/path argument); CI invoking the CLI with an empty variable (e.g. $FILES unexpanded); wrong working directory where glob matches nothing is a related variant.

Understand the failure class

Background: "no subcommand specified" and "... is required": CLI errors when a required argument is missing — this error's family across 13 libraries.

Related errors

• Unable to minimize simple output
• Unable to output multiple templates in simple mode
• Name missing for template
• Must pass iterator to #each
• No environment passed to template

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