noctcore-contracts/require-error-cause
noctcore-contracts/require-error-cause
- Package
- contracts v1.1.0
- Preset
- recommended
- Severity
- error
- Autofix
--fix- Suggestions
- Yes
- Options
- Optional
- Type info
- Not needed
Re-throwing inside a catch without { cause } severs the chain to the original error. đź”§
When you catch an error and throw a new one, the new error is what reaches your logger. If you do not
forward the caught error as cause, the underlying failure — its message, stack, and any nested
cause — is gone. The stack you see points only at the re-throw site. Error’s standard cause
option (and every *Error subclass that forwards it) preserves the chain:
try { await db.query(sql);} catch (err) { throw new QueryError('load failed', { cause: err }); // chain intact}What it flags
Section titled “What it flags”A throw new SomeError(...) inside a catch block when no argument carries a cause property.
A throw nested in a closure declared inside the catch is still flagged: the binding is genuinely in
scope there. Nested try/catch uses the nearest binding.
// drops the cause: autofixes to `new Error('failed', { cause: err })`try { work(); } catch (err) { throw new Error('failed'); }
// a custom error: reported with a suggestion, not an autofixtry { work(); } catch (err) { throw new HttpError('failed', { status: 500 }); }try { work(); } catch (err) { throw new Error('failed', { cause: err }); }try { work(); } catch (err) { throw err; }For the built-in errors (Error, TypeError, RangeError, ReferenceError, SyntaxError,
EvalError, URIError) and any constructor listed in autofixConstructors, an autofix attaches
{ cause: <binding> }. For any other *Error / *Exception the same edit is offered as a
suggestion: a custom constructor may not take an options argument in its last position, and
appending one is then a type error, or silently drops the cause in JS
(new AppError('E_RUN', 'run failed') would become a three-argument call). The edit:
- one argument (
new Error('msg')) → appends a new options object; - an existing options object → merges
causein; - an empty options object (
{}) → fills it.
A zero-argument new SomeError() is reported but not autofixed — inserting an options object as
the first argument could clobber a positional message the rule cannot see.
What it does not flag
Section titled “What it does not flag”Deliberately conservative:
- Only constructors whose simple name ends in
ErrororExceptionare treated as errors (Error,TypeError,ValidationError,HttpException). Throwingnew Response(...)for control flow is not policed. - Fires only when the enclosing catch binds a plain identifier (
catch (err)). A parameterlesscatch {}or a destructured binding (catch ({ message })) has no single name to attach, so the throw is left alone. - Any
causeproperty (whatever its value), and any spread the rule cannot see through, counts as “has a cause” and suppresses the report — a hand-written cause is never second-guessed. - A bare re-throw of the caught error (
throw err).
Options
Section titled “Options”| Option | Type | Default | Meaning |
|---|---|---|---|
autofixConstructors |
string[] |
the built-in error names | Constructors whose last argument takes { cause }, so the edit is applied by --fix. Setting it replaces the default. |
'noctcore-contracts/require-error-cause': ['error', { autofixConstructors: ['Error', 'TypeError', 'AppError'] }]When not to use it
Section titled “When not to use it”If your error classes do not accept an options object with cause (pre-ES2022 targets without a
polyfill), or you deliberately model errors without chaining, leave this rule off.