jQuery Deferred fail() Method

What You’ll Learn

The fail() method registers an error callback on a jQuery Deferred. It runs when the operation is rejected — network failures, validation errors, or explicit reject() calls. This tutorial covers syntax, five examples, comparisons with done() and catch(), and best practices.

Introduction

Robust apps plan for failure. Servers return errors, networks drop, and user input fails validation. jQuery’s fail() method is the dedicated error path on a Deferred — the mirror image of done() for success.

Chain fail() after async work to log errors, show messages, retry requests, or fall back to cached data. Always pair it with done() (or handle both in then()) so neither outcome is ignored.

Understanding the fail() Method

fail() is part of jQuery’s Deferred Object API (since jQuery 1.5). Calling deferred.fail(errorHandler) queues your function. When the Deferred enters the rejected state — via reject(), a failed AJAX call, or a rejected promise in a chain — jQuery invokes each fail callback with the rejection arguments.

fail() does not run on success. Resolved Deferreds skip fail handlers and run done() instead.

📝 Syntax

General form of deferred.fail:

deferred.fail( failCallback [, failCallback ] )

Parameters

• failCallback — function executed when the Deferred rejects. Receives reject arguments (error message, jqXHR, status text, etc.). You may register multiple handlers.

Return value

• Returns the same Deferred object for chaining done(), always(), or another fail().

AJAX example

$.ajax({
  url: "/api/profile",
  method: "GET"
})
  .done(function (response) {
    renderProfile(response);
  })
  .fail(function (xhr, status, error) {
    console.error("Request failed:", status, error);
  });

Examples Gallery

Each example demonstrates error handling with jQuery Deferred. Use DevTools or the Try-it links to run them.

const dfd = $.Deferred();

dfd.fail(function (error) {
  console.error("fail:", error);
});

dfd.reject("Network error");

fail: Network error

$.ajax({
  url: "/api/profile",
  method: "GET"
})
  .done(function (response) {
    console.log("Success:", response);
  })
  .fail(function (xhr, status, error) {
    console.error("Request failed:", status, error);
  });

fail: error — 404 Not Found

const dfd = $.Deferred();

dfd.fail(function (err) {
  console.error("Log:", err);
});

dfd.fail(function (err) {
  showToast("Error: " + err);
});

dfd.fail(function () {
  reportToMonitoring("request_failed");
});

dfd.reject("timeout");

fail #1: log timeout
fail #2: show toast — timeout
fail #3: report to monitoring

function fetchItems() {
  const dfd = $.Deferred();

  setTimeout(function () {
    dfd.reject("503 Service Unavailable");
  }, 600);

  return dfd
    .done(function (items) {
      $("#list").text(items.join(", "));
    })
    .fail(function (error) {
      $("#list").text("Could not load items — " + error);
    });
}

Could not load items — 503 Service Unavailable

const dfd = $.Deferred();

dfd.reject("already failed");

dfd.fail(function (reason) {
  console.error("fail (registered late):", reason);
});

fail (registered late): already failed

🚀 Use Cases

• AJAX requests — handle network errors, HTTP 4xx/5xx, and invalid JSON responses.
• Animation effects — recover or notify when an animation callback rejects.
• Promise chains — centralize error handling at the end of multi-step async pipelines.
• Timeouts — reject when work exceeds a limit and show a timeout message in fail().
• Fallback data — load cached content or default values when the primary request fails.

📝 Notes

• fail() never runs when the Deferred resolves — use done() for success.
• In jQuery 3+, catch(fn) is identical to fail(fn).
• Empty fail() handlers hide errors from users — always log or display something useful.
• Returning a value from fail() does not recover the chain; use catch recovery patterns or a new resolve in advanced cases.
• Check rejection state with state() or isRejected() when debugging.

💡 Best Practices