emberjs/ember.js · error · Error

Programmatic transitions by URL cannot be used within an Eng

Error message

Programmatic transitions by URL cannot be used within an Engine. Please use the route name instead.

What it means

When transitioning programmatically (transitionTo/replaceWith/transitionToRoute) from inside a routable Engine, the first argument must be a route name, not a URL. Because URLs cannot be namespaced into the engine's mount point, passing something that resemblesURL() throws this error.

Source

Thrown at packages/@ember/routing/lib/utils.ts:251

  Returns an arguments array where the route name arg is prefixed based on the mount point

  @private
*/
export function prefixRouteNameArg<T extends NamedRouteArgs | UnnamedRouteArgs>(
  route: Route,
  args: T
): T {
  let routeName: string;
  let owner = getOwner(route);
  assert('Expected route to have EngineInstance as owner', owner instanceof EngineInstance);

  let prefix = owner.mountPoint;

  // only alter the routeName if it's actually referencing a route.
  if (owner.routable && typeof args[0] === 'string') {
    routeName = args[0];
    if (resemblesURL(routeName)) {
      throw new Error(
        'Programmatic transitions by URL cannot be used within an Engine. Please use the route name instead.'
      );
    } else {
      routeName = `${prefix}.${routeName}`;
      args[0] = routeName;
    }
  }

  return args;
}

export function shallowEqual<A extends object, B extends object>(a: A, b: B): boolean {
  let aCount = 0;
  let bCount = 0;
  for (let kA in a) {
    if (Object.prototype.hasOwnProperty.call(a, kA)) {
      if (a[kA] !== (b as any)[kA]) {
        return false;

View on GitHub (pinned to 26f97246a8)

Solutions

1. Replace the URL string with the engine-local route name: this.transitionTo('posts.post', model)
2. If targeting a parent-app route, use the fully qualified route name
3. Convert URL-building helpers to route-name-based transitions

Example fix

// before
this.transitionTo('/posts/' + post.id);
// after
this.transitionTo('posts.post', post);

import { resemblesURL } from '@ember/routing/utils';
if (getOwner(this).mountPoint && resemblesURL(target)) {
  throw new Error('Use route names, not URLs, inside engines');
}

function isSafeEngineTransitionTarget(owner, target) { return !(owner.mountPoint && owner.routable && typeof target === 'string' && resemblesURL(target)); }

try { this.transitionTo(target); } catch (e) { if (/Programmatic transitions by URL/.test(e.message)) { this.transitionTo(urlToRouteName(target)); } else throw e; }

When it happens

Trigger: Calling this.transitionTo('/some/url') or transitionToRoute('/posts/1') inside a component/route/controller whose owner.mountPoint is set (routable engine) with a string starting with '/' or containing a URL pattern.

Common situations: Copy-pasted transition code from the app into an engine; refactoring transitions to use URL strings; helper utilities that build URLs instead of route names.

Related errors

• You attempted to mount the engine '${name}', but it is not r
• Defining a route serializer on route '${name}' outside an En
• Defining a custom serialize method on an Engine route is not
• TransitionError
• More context objects were passed than there are dynamic segm

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