JavaScript Promise finally() Method

Beginner
6 min read
Updated: Nov 2026
3 examples
Instance method

Definition

promise.finally(onFinally) runs a function when a promise is settled, whether it fulfilled or rejected. It is made for cleanup, such as hiding a loading spinner. Your function gets no arguments, and its return value is ignored: the original value or error passes through. Only a throw (or a rejected promise) inside finally can change the result.

Remember
promise.finally(onFinally)

onFinally()        → no arguments at all
runs after success → yes
runs after failure → yes
return value       → ignored
value or reason    → passes through unchanged
onFinally throws   → new promise rejects with that error

Syntax

Call finally on a promise, usually after your then and catch steps, and pass one function without parameters.

JavaScript
promise.finally(onFinally)

promise
  .then(useValue)
  .catch(showError)
  .finally(cleanUp)
CallWhat it does
promise.finally(onFinally)Run onFinally() after the promise fulfills or rejects.
promise.then(a).catch(b).finally(c)The classic order: success, error, then cleanup that always runs.

Added in ES2018, later than then() and catch(). It returns a new promise, so you can keep chaining.

Library declarations
JavaScript
promise.finally(onFinally)   // returns a new Promise
// onFinally() is called with no arguments

Parameters

ParameterDescription
onFinallyA function called with no arguments once the promise settles. Its return value is ignored, but if it returns a promise, the chain waits for that promise first.

Return Value

Return ValueDescription
PromiseA new promise with the same value or reason as the original. It rejects instead if onFinally throws or returns a rejected promise.

JavaScript Examples

Example 1 — Cleanup After Success and Failure

A spinner must disappear whether the data arrived or not. Without finally() you would repeat that line twice.

JavaScript
const spinner = { visible: false };

function loadData(shouldFail) {
  if (shouldFail) {
    return Promise.reject(new Error("could not load"));
  }
  return Promise.resolve("data ready");
}

function load(shouldFail) {
  spinner.visible = true;
  console.log("spinner visible: " + spinner.visible);
  return loadData(shouldFail)
    .then((text) => {
      console.log("success: " + text);
    })
    .catch((error) => {
      console.log("error: " + error.message);
    })
    .finally(() => {
      spinner.visible = false;
      console.log("spinner visible: " + spinner.visible);
    });
}

load(false).then(() => load(true));
Try It Yourself

How It Works

  1. Turn the spinner on first. load() sets spinner.visible to true before the data is requested, so the user sees that work is going on.
  2. Cleanup after a good result. The first call fulfills. then prints the data, then finally switches the spinner off.
  3. Cleanup after a bad result. The second call rejects and catch prints the message. finally still hides the spinner, with the same single block of code.

Example 2 — finally() Does Not Change the Result

See what finally() receives and returns, first for a fulfilled promise and then for a rejected one.

JavaScript
Promise.resolve("original value")
  .finally((...args) => {
    console.log("arguments received: " + args.length);
    return "this is ignored";
  })
  .then((value) => {
    console.log("value after finally: " + value);
    return Promise.reject(new Error("original error"))
      .finally(() => {
        console.log("cleanup runs for a rejection too");
        return "this is ignored too";
      })
      .catch((error) => {
        console.log("reason after finally: " + error.message);
      });
  });
Try It Yourself

How It Works

  1. No arguments arrive. The rest parameter ...args collects everything passed in, and its length is 0.
  2. The return value is dropped. The function returns "this is ignored", yet the next then still receives "original value".
  3. Errors pass through too. For the rejected promise the cleanup runs, and the very same original error reaches the catch after it.

Example 3 — Throwing or Waiting Inside finally()

Cleanup code can fail, or be slow. See what each case does to the chain.

JavaScript
function cleanupThatFails() {
  throw new Error("cleanup failed");
}

function slowCleanup() {
  return new Promise((resolve) => {
    setTimeout(() => {
      console.log("slow cleanup done");
      resolve("ignored");
    }, 30);
  });
}

Promise.reject(new Error("first error"))
  .finally(cleanupThatFails)
  .catch((error) => {
    console.log("1) " + error.message);
    return Promise.resolve("final value").finally(slowCleanup);
  })
  .then((value) => {
    console.log("2) " + value);
  });
Try It Yourself

How It Works

  1. A throw inside finally wins. The promise rejected with first error, but cleanupThatFails throws, so the catch sees cleanup failed. A fulfilled value would be replaced the same way.
  2. A returned promise is awaited. finally waits about 30 ms for slowCleanup before the chain moves on, so its message prints before line 2.
  3. The cleanup result is ignored. slowCleanup resolves with "ignored", yet the next then gets "final value", the original result.

Browser & Runtime Support

Promise.prototype.finally() arrived in ES2018, later than the ES2015 then() and catch().

✓ Widely available · ES2018

Promise.prototype.finally()

Supported in Chrome 63+, Firefox 58+, Safari 11.1+, Edge 18+, and Node.js 10+. Not available in Internet Explorer.

Wide All current browsers
Google Chrome Chrome 63+
Supported
Mozilla Firefox Firefox 58+
Supported
Apple Safari Safari 11.1+
Supported
Microsoft Edge Edge 18+
Supported
Node.js Node.js 10+
Supported
Deno Recent versions
Supported
Internet Explorer No support
Not supported
finally() Very good

Bottom line: Safe for every current browser and Node.js release. Very old browsers need a polyfill.

Frequently Asked Questions

It runs a function after the promise is settled, whether it fulfilled or rejected. It is meant for cleanup work such as hiding a spinner or closing a file.
No. The function is called with no arguments, so it cannot read the result. Use then() or catch() for that. The original result still passes through.
You could, but you would write the same code twice. With finally() the cleanup is written once and always runs.
Not by returning a value, because that value is ignored. Only a thrown error or a rejected promise returned from finally() changes the result.
It is part of ES2018: Chrome 63, Firefox 58, Safari 11.1, Edge 18, and Node.js 10 and newer. Internet Explorer does not support it.

Next: then()

Learn how then() chains steps together and why every then returns a new promise.

then() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

11 people found this page helpful