emberjs/ember.js · error · UnrecognizedURLError

${this.url}

Error message

${this.url}

What it means

URLTransitionIntent.applyToState throws UnrecognizedURLError whose message is just the URL, because the router's recognizer could not match the URL to any defined route. There is no route map entry (including wildcard) matching this path.

Source

Thrown at packages/router_js/lib/transition-intent/url-transition-intent.ts:25

import { merge } from '../utils';

export default class URLTransitionIntent<R extends Route> extends TransitionIntent<R> {
  preTransitionState?: TransitionState<R>;
  url: string;
  constructor(router: Router<R>, url: string, data?: object) {
    super(router, data);
    this.url = url;
    this.preTransitionState = undefined;
  }

  applyToState(oldState: TransitionState<R>) {
    let newState = new TransitionState<R>();
    let results = this.router.recognizer.recognize(this.url),
      i,
      len;

    if (!results) {
      throw new UnrecognizedURLError(this.url);
    }

    let statesDiffer = false;
    let _url = this.url;

    // Checks if a handler is accessible by URL. If it is not, an error is thrown.
    // For the case where the handler is loaded asynchronously, the error will be
    // thrown once it is loaded.
    function checkHandlerAccessibility(handler: R) {
      if (handler && handler.inaccessibleByURL) {
        throw new UnrecognizedURLError(_url);
      }

      return handler;
    }

    for (i = 0, len = results.length; i < len; ++i) {
      let result = results[i]!;

View on GitHub (pinned to 26f97246a8)

Solutions

1. Add the missing route (or a catch-all this.route('not-found', { path: '*:' }) wildcard) to the router map.
2. Check rootURL / baseURL configuration matches how the app is served.
3. Fix the source of the bad URL (redirect, link, server rewrite).
4. Handle UnrecognizedURLError in a default handler for a friendly 404 page.

Example fix

// before (router map has no match for /legacy-page)
// after
this.route('legacy-page', { path: '/legacy-page' }, function() { this.route('index'); });
// or a catch-all:
this.route('not-found', { path: '*:' });

function isKnownPath(router, url) {
  return router.recognizer.recognize(url) !== undefined; // pre-check like applyToState does
}
if (!isKnownPath(router, '/legacy-page')) redirect('/');

null

router.handleURL(url).catch(e => {
  if (e.name === 'UnrecognizedURLError') { router.transitionTo('not-found'); }
  else throw e;
});

When it happens

Trigger: router.handleURL('/some/path'), url transitions on initial load, or replaceState/pushState to a path with no matching route definition.

Common situations: Deployed app served at a path prefix the router doesn't know (rootURL mismatch); user bookmarked a removed route; server/proxy rewrites stripped a path segment; typo in a redirect target.

Related errors

• ${_url}
• You attempted to mount the engine '${name}', but it is not r
• Defining a route serializer on route '${name}' outside an En
• Programmatic transitions by URL cannot be used within an Eng
• Defining a custom serialize method on an Engine route is not

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