Skip to main content

only-throw-error

Disallow throwing non-Error values as exceptions.

✅

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

💭

This rule requires type information to run, which comes with performance tradeoffs.

🧱

This is an "extension" rule that replaces a core ESLint rule to work with TypeScript. See Rules > Extension Rules.

This rule extends the base no-throw-literal rule from ESLint core. It uses type information to determine which values are Errors.

It is considered good practice to only throw the Error object itself or an object using the Error object as base objects for user-defined exceptions. The fundamental benefit of Error objects is that they automatically keep track of where they were built and originated.

Migration from no-throw-literal

This extension rule was formerly known as @typescript-eslint/no-throw-literal. The new name is a drop-in replacement with identical functionality.

Examples​

This rule is aimed at maintaining consistency when throwing exceptions by disallowing throwing values that are not Error objects.

throw 'error';

throw 0;

throw undefined;

function getErrorString(): string {
  return '';
}
throw getErrorString();

const foo = {
  bar: 'error string',
};
throw foo.bar;

class SomeClass {
  // ...
}
throw new SomeClass();
Open in Playground

How to Use​

eslint.config.mjs
export default tseslint.config({
  rules: {
    // Note: you must disable the base rule as it can report incorrect errors
    "no-throw-literal": "off",
    "@typescript-eslint/only-throw-error": "error"
  }
});

Try this rule in the playground ↗

Options​

See eslint/no-throw-literal's options.

This rule adds the following options:

interface Options {
  /**
   * Type specifiers that can be thrown.
   */
  allow?: (
    | {
        from: 'file';
        name: string[] | string;
        path?: string;
      }
    | {
        from: 'lib';
        name: string[] | string;
      }
    | {
        from: 'package';
        name: string[] | string;
        package: string;
      }
    | string
  )[];

  /**
   * Whether to allow rethrowing caught values that are not `Error` objects.
   */
  allowRethrowing?: boolean;

  /**
   * Whether to always allow throwing values typed as `any`.
   */
  allowThrowingAny?: boolean;

  /**
   * Whether to always allow throwing values typed as `unknown`.
   */
  allowThrowingUnknown?: boolean;
}

const defaultOptions: Options = {
  allow: [],
  allowRethrowing: true,
  allowThrowingAny: true,
  allowThrowingUnknown: true,
};

allowThrowingAny​

When set to true, this option allows throwing values typed as any.

Examples of correct code with { allowThrowingAny: true }:

function throwAny(value: any) {
  throw value;
}
Open in Playground

allowThrowingUnknown​

When set to true, this option allows throwing values typed as unknown.

Examples of correct code with { allowThrowingUnknown: true }:

function throwUnknown(value: unknown) {
  throw value;
}
Open in Playground

allowRethrowing​

When set to true, this option allows throwing caught values. This is intended to be used in order to make patterns involving rethrowing exceptions less painful for users who set allowThrowingAny/allowThrowingUnknown to false.

Examples of correct code with { allowRethrowing: true, allowThrowingAny: false, allowThrowingUnknown: false }:

declare function mightThrow(): void;
declare class SomeSpecificError extends Error {
  // ...
}

function foo() {
  try {
    mightThrow();
  } catch (e) {
    if (e instanceof SomeSpecificError) {
      // handle specific error ...
      return;
    }

    // unexpected error that we shouldn't catch.
    throw e;
  }
}

declare function mightReject(): Promise<void>;

mightReject().catch(e => {
  if (e instanceof SomeSpecificError) {
    // handle specific error ...
    return;
  }

  // unexpected error that we can't handle
  throw e;
});

declare function log(message: string): void;

function bar() {
  log('starting bar()');
  let wasError = false;
  try {
    // ...
  } catch (e) {
    wasError = true;
    throw e;
  } finally {
    log(`completed bar() ${wasError ? 'with error' : 'successfully'}`);
  }
}
Open in Playground
note

While it makes sense to rethrow errors in some cases, it is likely more common that one would want to create a new Error and set its cause appropriately.

function foo() {
  try {
    // ...
  } catch (e) {
    throw new Error('Could not complete foo()', { cause: e });
  }
}

allow​

This option takes the shared TypeOrValueSpecifier format to allow throwing values that are not Error objects. While we strongly recommend that you only create custom error classes that extend Error, this option can be useful for throwing errors defined by libraries that do not follow this convention.

Examples of code for this rule with:

{
  "allow": [{ "from": "file", "name": "CustomError" }],
}
class CustomError /* does NOT extend Error */ {
  // ...
}

throw new CustomError();
Open in Playground

When Not To Use It​

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​

Taken with ❤️ from ESLint core.