fail()?deferred.fail(failCallbacks) adds handlers that run when a Deferred is rejected (failure). Available since jQuery 1.5. It returns the Deferred so you can chain more methods.
dfd.fail(fn)
dfd.fail(fn1, fn2)
dfd.fail([fn1, fn2], fn3)
reject("err") → fail handlers run with "err"
resolve(...) → fail does NOT run
$.get(url).fail(fn) // jqXHR error| Need | Use |
|---|---|
| On failure | dfd.fail(fn) |
| On success | dfd.done(fn) |
| Either outcome | dfd.always(fn) |
fail()Create or receive a Deferred/Promise, attach fail, then reject (or wait for AJAX to fail).
$.Deferred()) or a jqXHR from $.ajax / $.get..fail(function (reason) { ... }) — pass a function or an array of functions.reject(reason) (or let AJAX fail).done / always as needed.| Piece | Required? | Role |
|---|---|---|
| Deferred / jqXHR | Yes | Object that can reject |
failCallbacks | Yes | Function or array of functions |
| Return value | — | Same Deferred (chainable) |
function fail(deferred, callbacks):
queue = flatten(callbacks) // functions and arrays
add each callback to failure list
when deferred.reject(args...):
for each fn in failure list (in order):
fn(args...)
return deferred // chainableKeep these facts handy while wiring error handlers.
| Topic | Detail |
|---|---|
| Syntax | deferred.fail(failCallbacks [, failCallbacks ]) |
| Since | jQuery 1.5 (catch alias since 3.0) |
| Runs when | Deferred is rejected |
| Arguments | Same values passed to reject / rejectWith |
| Multiple handlers | Functions or arrays; order preserved |
| Late attach | If already rejected → runs immediately |
| Returns | The Deferred (chainable) |
Pick a scenario and see how fail() behaves on reject.
Short, copy-ready snippets. Open DevTools Console, or use Try It Yourself for a live editor.
Attach fail(), then reject() with a reason.
var dfd = $.Deferred();
dfd.fail(function (error) {
console.log("fail: " + error);
});
dfd.reject("Network error");
// fail: Network error$.Deferred() starts in the pending state.fail(fn) queues the error callback.reject("Network error") settles as failure.Pass functions or arrays; they run in registration order (per the API docs).
var dfd = $.Deferred();
var lines = [];
function logErr(msg) { lines.push("log: " + msg); }
function showErr(msg) { lines.push("ui: " + msg); }
function track(msg) { lines.push("track: " + msg); }
dfd.fail([logErr, showErr], track);
dfd.reject("timeout");
console.log(lines.join(" | "));
// log: timeout | ui: timeout | track: timeout[logErr, showErr] adds both callbacks in order.track also receives "timeout".reject can pass several values — same shape as jqXHR .fail(xhr, status, error).
var dfd = $.Deferred();
dfd.fail(function (xhr, status, error) {
console.log(status); // error
console.log(error); // Not Found
console.log(xhr.status); // 404
});
dfd.reject({ status: 404 }, "error", "Not Found");$.ajax().fail often gets (jqXHR, textStatus, errorThrown).status / error for messages; inspect xhr for status codes.If the Deferred is already rejected, a new fail() still runs right away.
var dfd = $.Deferred();
dfd.reject("already failed");
dfd.fail(function (error) {
console.log("fail (late): " + error);
});
// fail (late): already failedreject happens before any handler is attached.fail(fn) sees the Deferred is already rejected.fn with the stored rejection reason.Check these before relying on fail() alone.
fail() never runs on resolve. Always pair with done() or a fulfillment branch on then().
catch needs jQuery 3+catch() is an alias for fail() since 3.0. Stick with fail() if you still support jQuery 1.x / 2.x.
fail vs then chainingfail() returns the same Deferred. Prefer then(null, onRejected) or catch() when you need to recover and continue a promise chain.
A Deferred rejects or resolves once. Extra reject calls are ignored; late fail handlers still see the first reason.
deferred.fail() has shipped since jQuery 1.5 and works in all modern browsers with jQuery loaded. It is part of the Deferred Object API (also used by jqXHR). catch() as an alias needs jQuery 3.0+.
Supported everywhere jQuery Deferred runs in the browser. Use it for error callbacks on Deferred and AJAX objects.
Bottom line: Call dfd.fail(fn) for errors. Pair with done() for success. Works on Deferred and jqXHR since jQuery 1.5.
| Approach | Cost | Best for |
|---|---|---|
dfd.fail(fn) | O(k) handlers | Error-only side effects |
dfd.catch(fn) | O(k) (alias) | Promise-style naming (3+) |
dfd.always(fn) | O(k) | Shared cleanup |
Handler cost is usually tiny compared with the async work (network, timers). Prefer clear success/error separation over micro-optimizing callback count.
done() / always() for success and cleanup.catch() ≡ fail() in jQuery 3+.One line: dfd.fail(fn) runs on reject only — queue error work, and pair with done() for the success path.
Check whether a Deferred has already been rejected.
9 people found this page helpful