emberjs/ember.js · critical · Error

Cannot call `compile` with only the template compiler loaded

Error message

Cannot call `compile` with only the template compiler loaded. Please load `ember.debug.js` or `ember.prod.js` prior to calling `compile`.

What it means

Ember's compile() needs the runtime template function loaded from the full Ember build (ember.debug.js / ember.prod.js). If the standalone template compiler package is loaded without it, the `template` binding is absent, so compile throws instead of producing a broken TemplateFactory.

Source

Thrown at packages/ember-template-compiler/lib/system/compile.ts:22

import type { EmberPrecompileOptions } from '../types';
import precompile from './precompile';
import type { SerializedTemplateWithLazyBlock, TemplateFactory } from '@glimmer/interfaces';
import { template } from '@ember/-internals/glimmer';

/**
  Uses HTMLBars `compile` function to process a string into a compiled template.
  This is not present in production builds.
  @private
  @method compile
  @param {String} templateString This is the string to be compiled by HTMLBars.
  @param {Object} options This is an options hash to augment the compiler options.
*/
export default function compile(
  templateString: string,
  options: Partial<EmberPrecompileOptions> = {}
): TemplateFactory {
  if (!template) {
    throw new Error(
      'Cannot call `compile` with only the template compiler loaded. Please load `ember.debug.js` or `ember.prod.js` prior to calling `compile`.'
    );
  }

  return template(evaluate(precompile(templateString, options)));
}

function evaluate(precompiled: string): SerializedTemplateWithLazyBlock {
  return new Function(`return ${precompiled}`)();
}

View on GitHub (pinned to 26f97246a8)

Solutions

Load ember.debug.js (dev) or ember.prod.js (prod) before any compile() call
Reorder imports so Ember's runtime loads before the compiler is invoked
Avoid runtime compile() in production — precompile templates at build time
If compiling in Node/tests, ensure the full Ember environment (or @glimmer runtime + template factory) is available

Example fix

// before
import compile from 'ember-template-compiler/system/compile';
const factory = compile('<h1>Hi</h1>');
// after
import 'ember'; // loads ember.debug.js / ember.prod.js first
import compile from 'ember-template-compiler/system/compile';
const factory = compile('<h1>Hi</h1>');

Defensive patterns

Strategy: try-catch

Validate before calling

import { _templateFactory } from 'ember'; // ensure runtime loaded
if (typeof window?.DS === 'undefined' && typeof require('ember') === 'undefined') { throw new Error('Load ember.debug.js/prod.js before compile()'); }

Try / catch

import compile from 'ember-template-compiler/system/compile';
try { factory = compile(src); } catch (e) { if (e.message.includes('only the template compiler loaded')) { await import('ember').then(() => compile(src)); } else { throw e; } }

Prevention

Precompile templates at build time; avoid runtime compile()
Ensure the full Ember bundle loads before any compile call
Check import order in test harnesses and shims
Never invoke compile at module top level before app boot

When it happens

Trigger: Calling compile() in an environment where only @ember/-template-compiler / the precompiler bundle is loaded and the main ember bundle defining `template` was never loaded or loaded after compile ran.

Common situations: Browser test setups importing only the template compiler; build-tool misconfiguration dropping ember.debug.js/prod.js; executing compile() at module top level before Ember finishes loading; using compile in Node with only the compiler installed.

Related errors

AI-assisted analysis of emberjs/ember.js@26f97246a8 (2026-09-01). Data as JSON: /api/errors/e4e019f1defced0a. Report an issue: GitHub.