jashkenas/backbone · error · Error

A "url" property or function must be specified

Error message

A "url" property or function must be specified

What it means

urlError is Backbone's fallback thrown by Model/Collection sync when a fetch/save/destroy/sync call needs a URL but neither a 'url' nor 'urlRoot' property (or function) is defined. Backbone refuses to build a request it cannot address, so it throws synchronously. It's a configuration error on the model/collection, not a network failure.

Source

Thrown at backbone.js:2143

    // Set the prototype chain to inherit from `parent`, without calling
    // `parent`'s constructor function and add the prototype properties.
    child.prototype = _.create(parent.prototype, protoProps);
    child.prototype.constructor = child;

    // Set a convenience property in case the parent's prototype is needed
    // later.
    child.__super__ = parent.prototype;

    return child;
  };

  // Set up inheritance for the model, collection, router, view and history.
  Model.extend = Collection.extend = Router.extend = View.extend = History.extend = extend;

  // Throw an error when a URL is needed, and none is supplied.
  var urlError = function() {
    throw new Error('A "url" property or function must be specified');
  };

  // Wrap an optional error callback with a fallback error event.
  var wrapError = function(model, options) {
    var error = options.error;
    options.error = function(resp) {
      if (error) error.call(options.context, model, resp, options);
      model.trigger('error', model, resp, options);
    };
  };

  // Provide useful information when things go wrong. This method is not meant
  // to be used directly; it merely provides the necessary introspection for the
  // external `debugInfo` function.
  Backbone._debug = function() {
    return {root: root, _: _};
  };

View on GitHub (pinned to f229c75b19)

Solutions

1. Define urlRoot on the model: 'urlRoot: "/api/users"' (fetch/save/destroy will hit /api/users/<id>).
2. Define a url function for dynamic or nested URLs: 'url: function(){ return "/api/users/" + this.id; }'.
3. Pass an explicit url in options: model.fetch({url: "/api/users/123"}).
4. Attach the model to a Collection that has a url, so the model inherits the collection's URL.
5. Verify the property is spelled 'url'/'urlRoot' and defined before the first fetch/save/destroy call.

Example fix

// before
var User = Backbone.Model.extend({});
new User({id: 42}).fetch(); // throws: A "url" property or function must be specified

// after
var User = Backbone.Model.extend({urlRoot: '/api/users'});
new User({id: 42}).fetch(); // GET /api/users/42

function hasUrlTarget(modelOrCollection) {
  if (modelOrCollection instanceof Backbone.Model) {
    return typeof modelOrCollection.urlRoot !== 'undefined' ||
           typeof modelOrCollection.url !== 'undefined' ||
           (modelOrCollection.collection && modelOrCollection.collection.url);
  }
  return typeof modelOrCollection.url !== 'undefined';
}
if (!hasUrlTarget(user)) throw new Error('Model must define url or urlRoot before fetch/save');

function isSyncable(m) {
  return !!(m.urlRoot || typeof m.url === 'function' || typeof m.url === 'string' ||
            (m.collection && m.collection.url));
}

try {
  model.fetch();
} catch (e) {
  if (/url.*property or function must be specified/.test(e.message)) {
    model.fetch({url: '/api/' + model.constructor.name.toLowerCase() + 's/' + model.id});
  } else { throw e; }
}

When it happens

Trigger: Calling model.fetch()/save()/destroy() on a Model with no url or urlRoot and that is not part of a collection with a url; calling collection.fetch() on a Collection without a url; calling Backbone.sync directly with options.url undefined for an unsaved, collection-less model.

Common situations: Forgetting to define url/urlRoot on a standalone model (especially one constructed without a collection); renaming/refactoring the url property; defining url on the instance after construction but after calling fetch; subclassing Model and dropping the url config from the parent; typo like 'urls' instead of 'url'.

Related errors

• Cannot sort a set without a comparator
• Backbone.history has already been started

AI-assisted analysis of jashkenas/backbone@f229c75b19 (2026-08-28). Data as JSON: /api/errors/68857950a5eb6207. Report an issue: GitHub.