no-floating-promises

Require Promise-like statements to be handled appropriately.

✅

Extending "plugin:@typescript-eslint/recommended-type-checked" in an ESLint configuration enables this rule.

💡

Some problems reported by this rule are manually fixable by editor suggestions.

💭

This rule requires type information to run.

A "floating" Promise is one that is created without any code set up to handle any errors it might throw. Floating Promises can cause several issues, such as improperly sequenced operations, ignored Promise rejections, and more.

This rule will report Promise-valued statements that are not treated in one of the following ways:

• Calling its .then() with two arguments
• Calling its .catch() with one argument
• awaiting it
• returning it
• voiding it

This rule also reports when an Array containing Promises is created and not properly handled. The main way to resolve this is by using one of the Promise concurrency methods to create a single Promise, then handling that according to the procedure above. These methods include:

• Promise.all()
• Promise.allSettled()
• Promise.any()
• Promise.race()

tip

no-floating-promises only detects apparently unhandled Promise statements. See no-misused-promises for detecting code that provides Promises to logical locations such as if statements.

See Using promises (error handling) on MDN for a detailed writeup on Promise error-handling.

Flat Config

eslint.config.mjs

export default tseslint.config({
  rules: {
    "@typescript-eslint/no-floating-promises": "error"
  }
});

Legacy Config

.eslintrc.cjs

module.exports = {
  "rules": {
    "@typescript-eslint/no-floating-promises": "error"
  }
};

Try this rule in the playground ↗

Examples

❌ Incorrect

const promise = new Promise((resolve, reject) => resolve('value'));
promise;

async function returnsPromise() {
  return 'value';
}
returnsPromise().then(() => {});

Promise.reject('value').catch();

Promise.reject('value').finally();

[1, 2, 3].map(async x => x + 1);

Open in Playground

✅ Correct

const promise = new Promise((resolve, reject) => resolve('value'));
await promise;

async function returnsPromise() {
  return 'value';
}

void returnsPromise();

returnsPromise().then(
  () => {},
  () => {},
);

Promise.reject('value').catch(() => {});

await Promise.reject('value').finally(() => {});

await Promise.all([1, 2, 3].map(async x => x + 1));

Open in Playground

Options

This rule accepts the following options:

type Options = [
  {
    /** Type specifiers of functions whose calls are safe to float. */
    allowForKnownSafeCalls?: (
      | {
          from: 'file';
          name: [string, ...string[]] | string;
          path?: string;
        }
      | {
          from: 'lib';
          name: [string, ...string[]] | string;
        }
      | {
          from: 'package';
          name: [string, ...string[]] | string;
          package: string;
        }
      | string
    )[];
    /** Type specifiers that are known to be safe to float. */
    allowForKnownSafePromises?: (
      | {
          from: 'file';
          name: [string, ...string[]] | string;
          path?: string;
        }
      | {
          from: 'lib';
          name: [string, ...string[]] | string;
        }
      | {
          from: 'package';
          name: [string, ...string[]] | string;
          package: string;
        }
      | string
    )[];
    /** Whether to check all "Thenable"s, not just the built-in Promise type. */
    checkThenables?: boolean;
    /** Whether to ignore async IIFEs (Immediately Invoked Function Expressions). */
    ignoreIIFE?: boolean;
    /** Whether to ignore `void` expressions. */
    ignoreVoid?: boolean;
  },
];

const defaultOptions: Options = [
  {
    allowForKnownSafeCalls: [],
    allowForKnownSafePromises: [],
    checkThenables: false,
    ignoreIIFE: false,
    ignoreVoid: true,
  },
];

checkThenables

Whether to check all "Thenable"s, not just the built-in Promise type. Default: false.

A "Thenable" value is an object which has a then method, such as a Promise. Other Thenables include TypeScript's built-in PromiseLike interface and any custom object that happens to have a .then().

The checkThenables option triggers no-floating-promises to also consider all values that satisfy the Thenable shape (a .then() method that takes two callback parameters), not just Promises. This can be useful if your code works with older Promise polyfills instead of the native Promise class.

❌ Incorrect

declare function createPromiseLike(): PromiseLike<string>;

createPromiseLike();

interface MyThenable {
  then(onFulfilled: () => void, onRejected: () => void): MyThenable;
}

declare function createMyThenable(): MyThenable;

createMyThenable();

Open in Playground

✅ Correct

declare function createPromiseLike(): PromiseLike<string>;

await createPromiseLike();

interface MyThenable {
  then(onFulfilled: () => void, onRejected: () => void): MyThenable;
}

declare function createMyThenable(): MyThenable;

await createMyThenable();

Open in Playground

ignoreVoid

Whether to ignore void expressions. Default: true.

Placing the void operator in front of a Promise can be a convenient way to explicitly mark that Promise as intentionally not awaited.

warning

Voiding a Promise doesn't handle it or change the runtime behavior. The outcome is just ignored, like disabling the rule with an ESLint disable comment. Such Promise rejections will still be unhandled.

Examples of correct code for this rule with { ignoreVoid: true }:

async function returnsPromise() {
  return 'value';
}
void returnsPromise();

void Promise.reject('value');

Open in Playground

When this option is set to true, if you are using no-void, you should turn on the allowAsStatement option.

ignoreIIFE

Whether to ignore async IIFEs (Immediately Invoked Function Expressions). Default: false.

Examples of correct code for this rule with { ignoreIIFE: true }:

await (async function () {
  await res(1);
})();

(async function () {
  await res(1);
})();

Open in Playground

allowForKnownSafePromises

Type specifiers that are known to be safe to float. Default: [].

For example, you may need to do this in the case of libraries whose APIs return Promises whose rejections are safely handled by the library.

This option takes the shared TypeOrValueSpecifier format.

Examples of code for this rule with:

{
  "allowForKnownSafePromises": [
    { "from": "file", "name": "SafePromise" },
    { "from": "lib", "name": "PromiseLike" },
    { "from": "package", "name": "Bar", "package": "bar-lib" }
  ]
}

❌ Incorrect

let promise: Promise<number> = Promise.resolve(2);
promise;

function returnsPromise(): Promise<number> {
  return Promise.resolve(42);
}

returnsPromise();

Open in Playground

✅ Correct

// promises can be marked as safe by using branded types
type SafePromise = Promise<number> & { __linterBrands?: string };

let promise: SafePromise = Promise.resolve(2);
promise;

function returnsSafePromise(): SafePromise {
  return Promise.resolve(42);
}

returnsSafePromise();

Open in Playground

allowForKnownSafeCalls

Type specifiers of functions whose calls are safe to float. Default: [].

For example, you may need to do this in the case of libraries whose APIs may be called without handling the resultant Promises.

This option takes the shared TypeOrValueSpecifier format.

Examples of code for this rule with:

{
  "allowForKnownSafeCalls": [
    { "from": "file", "name": "safe", "path": "input.ts" }
  ]
}

❌ Incorrect

declare function unsafe(...args: unknown[]): Promise<void>;

unsafe('...', () => {});

Open in Playground

✅ Correct

declare function safe(...args: unknown[]): Promise<void>;

safe('...', () => {});

Open in Playground

When Not To Use It

This rule can be difficult to enable on large existing projects that set up many floating Promises. Alternately, if you're not worried about crashes from floating or misused Promises -such as if you have global unhandled Promise handlers registered- then in some cases it may be safe to not use this rule. You might consider using voids and/or ESLint disable comments for those specific situations instead of completely disabling this rule.

Related To

• no-misused-promises

Further Reading

• "Using Promises" MDN documentation. Note especially the sections on Promise rejection events and Composition.

---

Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting.

See Troubleshooting > Linting with Type Information > Performance if you experience performance degradations after enabling type checked rules.

Resources

• Rule source
• Test source