Unawaited promise in async JavaScript or TypeScript code

What this failure means

An async JavaScript or TypeScript function starts a promise-returning operation but never awaits or catches it. The rejection can escape the call site, turning a real failure into an unhandled rejection or a race that is hard to reproduce.

Diagnosis

An async JavaScript or TypeScript function starts a promise-returning operation but never awaits or catches it. The rejection can escape the call site, turning a real failure into an unhandled rejection or a race that is hard to reproduce.

Fix steps

1. await the promise at the call site so the failure propagates through the current function.
2. If the work is intentionally detached, attach an explicit .catch(...) that logs or forwards the error.
3. Prefer returning the promise instead of dropping it when the caller should own the lifecycle.
4. Add a regression test for the async path so the missing await does not come back.

Validation

• Run faultline inspect . from the repository root and confirm this source finding is absent or intentionally mitigated.
• Confirm the unawaited promise finding is resolved and the top source playbook still points at the intended file.

Why it matters

Unawaited promises are one of the easiest ways to hide a real failure in JavaScript and TypeScript. The caller can continue as if the work succeeded, while the rejection is routed to global handlers, logged too late, or lost entirely. In CI and server code, that can turn a bad response, a timeout, or a rejected network call into flaky behavior that is hard to trace back to the original line.

Prevention

• Use await by default in async functions.
• If work must be detached, centralize the fire-and-forget boundary and log failures there.
• Keep promise-returning helper functions small so tests can assert the returned rejection path directly.

Try it locally

make test
rg -n async .
make test
npm test

How Faultline detects it

Use faultline explain unawaited-promise to see the full playbook.

faultline analyze build.log
faultline explain unawaited-promise

Generated from playbooks/bundled/source/unawaited-promise.yaml. Do not edit directly.