jQuery Deferred catch() Method

What You’ll Learn

The catch() method attaches an error handler to a jQuery Deferred or promise chain. It runs when the operation is rejected or when a then() callback throws — giving you a familiar, Promise-style way to centralize failure handling.

Introduction

Async code fails — networks drop, APIs return errors, and validation throws. Without a dedicated error path, failures either crash your script or leave users staring at a broken UI. jQuery’s Deferred API gives you fail() for rejections; since jQuery 3.0, catch() offers the same behavior with Promise-style naming.

Use catch() at the end of a chain (or after any then()) to log errors, show messages, retry requests, or fall back to cached data — all in one readable place instead of scattering checks everywhere.

Understanding the catch() Method

catch() is part of jQuery’s Promises/A+ compatible Deferred interface (jQuery 3.0+). When you call deferred.catch(errorHandler), jQuery queues your function and invokes it when:

• The Deferred is rejected via reject() or rejectWith().
• A then() callback throws an exception.
• A then() callback returns a rejected promise or Deferred.

The handler receives the rejection reason — often a string, Error object, or AJAX error details. It does not run when the chain resolves successfully.

📝 Syntax

General form of deferred.catch:

deferred.catch( errorHandler [, errorHandler ] )

Parameters

• errorHandler — function executed when the Deferred is rejected or when an upstream then() fails. Receives the rejection reason as argument(s). You may register multiple handlers.

Return value

• Returns the same Deferred/promise object for chaining further then() or catch() calls.

Promise-style chain

myAsyncTask()
  .then(function (result) {
    return processResult(result);
  })
  .catch(function (error) {
    console.error("An error occurred:", error);
  });

Examples Gallery

Each example uses jQuery 3.7+ Deferred APIs. Use DevTools or the Try-it links to run them interactively.

const dfd = $.Deferred();

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

dfd.reject("Network timeout");

catch: Network timeout

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

  setTimeout(function () {
    dfd.resolve({ name: "Alex" });
  }, 200);

  return dfd
    .then(function (result) {
      console.log("Profile:", result.name);
    })
    .catch(function (error) {
      console.error("Failed:", error);
    });
}

Profile: Alex

$.Deferred()
  .resolve({ id: 0 })
  .then(function (data) {
    if (!data.id) {
      throw new Error("Invalid user id");
    }
    console.log("Valid id:", data.id);
  })
  .catch(function (err) {
    console.error("catch:", err.message);
  });

catch: Invalid user id

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

  setTimeout(function () {
    dfd.reject("Server unavailable (503)");
  }, 600);

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

Could not load items — Server unavailable (503)

function stepOne() {
  return $.Deferred().resolve(10).promise();
}

function stepTwo(value) {
  return $.Deferred().resolve(value * 2).promise();
}

function stepThree(value) {
  return $.Deferred().reject("Step 3 failed at " + value).promise();
}

stepOne()
  .then(stepTwo)
  .then(stepThree)
  .then(function (final) {
    console.log("success:", final);
  })
  .catch(function (error) {
    console.error("catch:", error);
  });

catch: Step 3 failed at 20

🚀 Use Cases

• Promise chains — attach one catch() after several then() steps to handle any failure in the pipeline.
• AJAX requests — show error toasts or fallback UI when $.ajax() rejects.
• Chained Deferreds — keep error logic consistent when each step returns a new promise.
• Validation errors — throw inside then() and let catch() format the message for users.
• Logging — record structured error context in one place before optional recovery.

📝 Notes

• catch() requires jQuery 3.0+. On older versions, use fail().
• catch is a reserved word in older ES5 strict contexts — jQuery still exposes it as a method name on objects.
• Returning a plain value from catch() can resume the chain with a resolved promise.
• Pair with always() when you also need cleanup on success.
• For brand-new code without jQuery, native Promise.catch() follows the same mental model.

💡 Best Practices