{"record":{"id":"18782e4f3eeeb0e4","repo":"emberjs/ember.js","slug":"programmatic-transitions-by-url-cannot-be-used-wit","errorCode":null,"errorMessage":"Programmatic transitions by URL cannot be used within an Engine. Please use the route name instead.","messagePattern":"Programmatic transitions by URL cannot be used within an Engine\\. Please use the route name instead\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/@ember/routing/lib/utils.ts","lineNumber":251,"sourceCode":"  Returns an arguments array where the route name arg is prefixed based on the mount point\n\n  @private\n*/\nexport function prefixRouteNameArg<T extends NamedRouteArgs | UnnamedRouteArgs>(\n  route: Route,\n  args: T\n): T {\n  let routeName: string;\n  let owner = getOwner(route);\n  assert('Expected route to have EngineInstance as owner', owner instanceof EngineInstance);\n\n  let prefix = owner.mountPoint;\n\n  // only alter the routeName if it's actually referencing a route.\n  if (owner.routable && typeof args[0] === 'string') {\n    routeName = args[0];\n    if (resemblesURL(routeName)) {\n      throw new Error(\n        'Programmatic transitions by URL cannot be used within an Engine. Please use the route name instead.'\n      );\n    } else {\n      routeName = `${prefix}.${routeName}`;\n      args[0] = routeName;\n    }\n  }\n\n  return args;\n}\n\nexport function shallowEqual<A extends object, B extends object>(a: A, b: B): boolean {\n  let aCount = 0;\n  let bCount = 0;\n  for (let kA in a) {\n    if (Object.prototype.hasOwnProperty.call(a, kA)) {\n      if (a[kA] !== (b as any)[kA]) {\n        return false;","sourceCodeStart":233,"sourceCodeEnd":269,"githubUrl":"https://github.com/emberjs/ember.js/blob/26f97246a8bf2e28edf26ac3093da2e86c04ffc5/packages/@ember/routing/lib/utils.ts#L233-L269","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Replace the URL string with the engine-local route name: this.transitionTo('posts.post', model)","If targeting a parent-app route, use the fully qualified route name","Convert URL-building helpers to route-name-based transitions"],"exampleFix":"// before\nthis.transitionTo('/posts/' + post.id);\n// after\nthis.transitionTo('posts.post', post);","handlingStrategy":"validation","validationCode":"import { resemblesURL } from '@ember/routing/utils';\nif (getOwner(this).mountPoint && resemblesURL(target)) {\n  throw new Error('Use route names, not URLs, inside engines');\n}","typeGuard":"function isSafeEngineTransitionTarget(owner, target) { return !(owner.mountPoint && owner.routable && typeof target === 'string' && resemblesURL(target)); }","tryCatchPattern":"try { this.transitionTo(target); } catch (e) { if (/Programmatic transitions by URL/.test(e.message)) { this.transitionTo(urlToRouteName(target)); } else throw e; }","preventionTips":["Inside engines always transitionTo by route name","Avoid URL-building helpers for navigation in routable engines","Review copy-pasted transitions from parent app code"],"tags":["ember","routing","engines","transition","url"],"backgroundTag":"url-transition-in-engine","analyzedSha":"26f97246a8bf2e28edf26ac3093da2e86c04ffc5","analyzedAt":"2026-09-01T05:01:28.182Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}