emberjs/ember.js · error · Error

Invalid helper manager compatibility specified; you specifie

Error message

Invalid helper manager compatibility specified; you specified ${managerAPI}, but only '3.23' is supported.

What it means

`helperCapabilities()` validates the manager API version. Unlike components (which accept '3.13'), helper managers only support '3.23', and a debugAssert throws with the version you actually passed. This ensures helper managers are built against the supported capability set.

Source

Thrown at packages/@glimmer/manager/lib/public/helper.ts:33

import {
  createComputeRef,
  createConstRef,
  UNDEFINED_REFERENCE,
} from '@glimmer/reference/lib/reference';

import type { ManagerFactory } from './index';

import { argsProxyFor } from '../util/args-proxy';
import { buildCapabilities, FROM_CAPABILITIES } from '../util/capabilities';

export function helperCapabilities<Version extends keyof HelperCapabilitiesVersions>(
  managerAPI: Version,
  options: Partial<HelperCapabilities> = {}
): HelperCapabilities {
  debugAssert(
    managerAPI === '3.23',
    () =>
      `Invalid helper manager compatibility specified; you specified ${managerAPI}, but only '3.23' is supported.`
  );

  if (
    DEBUG &&
    (!(options.hasValue || options.hasScheduledEffect) ||
      (options.hasValue && options.hasScheduledEffect))
  ) {
    throw new Error(
      'You must pass either the `hasValue` OR the `hasScheduledEffect` capability when defining a helper manager. Passing neither, or both, is not permitted.'
    );
  }

  if (DEBUG && options.hasScheduledEffect) {
    throw new Error(
      'The `hasScheduledEffect` capability has not yet been implemented for helper managers. Please pass `hasValue` instead'
    );
  }

View on GitHub (pinned to 26f97246a8)

Solutions

1. Change the version argument to exactly '3.23' in the helper manager's capabilities call
2. Import `capabilities` from @glimmer/manager (or Ember's re-export) to avoid mixing component/helper capability producers
3. Review helper manager docs for the supported version
4. Add a unit test that constructs the manager so the assert fires at build/test time

Example fix

// before
class MyHelperManager {
  capabilities = capabilities('3.13');
}
// after
class MyHelperManager {
  capabilities = capabilities('3.23', { hasValue: true });
}

import { capabilities } from '@glimmer/manager';
const version = '3.23';
if (version !== '3.23') throw new Error('helper managers only support 3.23');
const CAPS = capabilities('3.23', { hasValue: true });

const isHelperCapsVersion = (v: string): v is '3.23' => v === '3.23';

try { caps = helperCapabilities(version, opts); } catch (e) { if (/Invalid helper manager compatibility/.test(e.message)) caps = helperCapabilities('3.23', opts); else throw e; }

When it happens

Trigger: Calling `capabilities('3.13')` (copying the component-manager form) or any other version string when defining a helper manager's capabilities; passing a non-literal or undefined version.

Common situations: Copy-pasting capabilities from a component manager into a helper manager; helper manager examples from outdated blog posts; typos like '3.32'.

Related errors

• Invalid component manager compatibility specified
• You must pass either the `hasValue` OR the `hasScheduledEffe
• The `hasScheduledEffect` capability has not yet been impleme
• Custom component managers must have a `capabilities` propert

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