Error Tracking Coverage

Silently swallowed errors are one of the most dangerous patterns in production code.

architectureenforced by 1 rule

Context

Silently swallowed errors are one of the most dangerous patterns in production code. When a catch block does nothing or only logs to the console without reporting to an error tracking system (Sentry, Datadog, Bugsnag, etc.), the error goes unnoticed. The team has no visibility into failures, cannot measure error rates, and cannot prioritize fixes. Every caught error must be reported so that monitoring dashboards and alerting reflect the true state of the system.

Decision

All catch blocks must report errors to the error tracking system. Empty catch blocks and catch blocks that only use console.* without error reporting are not allowed. Errors may be intentionally suppressed only with an explicit comment explaining why.

Report caught errors to the error tracking system (e.g. Sentry.captureException(err)).
Never leave catch blocks empty.
If an error is intentionally ignored, add a comment explaining why.
Log the error with a structured logger in addition to reporting it.

Do's and Don'ts

Do

Report errors to the tracking system: Sentry.captureException(err).
Log errors with context: logger.error({ err, userId }, "Payment failed").
Re-throw errors when the caller should handle them.
Add a comment when intentionally suppressing an error: // Expected: file may not exist.

Don't

Leave catch blocks empty: catch (err) {}.
Only console.error without reporting: catch (err) { console.error(err) }.
Catch and ignore errors without explanation.
Catch broad error types when you only need to handle specific ones.

Consequences

Positive

All production errors are visible in the error tracking dashboard.
Error rates and trends can be monitored and alerted on.
No errors are silently lost in production.

Negative

Error tracking services have volume-based costs.
Developers must distinguish between expected and unexpected errors.

Enforcement rules

adrs/ARCH-003-error-tracking-coverage.rules.ts

/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "error-tracking-coverage": {
      description:
        "Catch blocks must report errors to the error tracking system, not silently swallow them",
      async check(ctx) {
        const sourceGlob = "**/*.{ts,tsx,js,jsx}";

        // Find empty catch blocks: catch (err) {} or catch {}
        const emptyCatchMatches = await ctx.grepFiles(
          /catch\s*(?:\([^)]*\))?\s*\{\s*\}/u,
          sourceGlob
        );

        for (const m of emptyCatchMatches) {
          if (
            m.file.includes(".test.") ||
            m.file.includes(".spec.") ||
            m.file.includes("__tests__")
          ) {
            continue;
          }
          ctx.report.warning({
            message:
              "Empty catch block silently swallows errors — report the error to the error tracking system.",
            file: m.file,
            line: m.line,
            fix: "Add error reporting: `Sentry.captureException(err)` or `logger.error({ err }, \"message\")`.",
          });
        }

        // Find catch blocks that only use console.* without error tracking
        // This is a heuristic: find files with catch blocks that have console but no
        // common error tracking calls
        const catchConsoleMatches = await ctx.grepFiles(
          /catch\s*\([^)]*\)\s*\{[^}]*console\.(log|warn|error)/u,
          sourceGlob
        );

        for (const m of catchConsoleMatches) {
          if (
            m.file.includes(".test.") ||
            m.file.includes(".spec.") ||
            m.file.includes("__tests__")
          ) {
            continue;
          }

          // Check if the catch block also has error tracking
          const hasTracking =
            /Sentry|captureException|captureMessage|Bugsnag|trackError|reportError|errorTracker/u.test(
              m.content
            );

          if (!hasTracking) {
            ctx.report.warning({
              message:
                "Catch block uses `console` logging without error tracking — report errors to the error tracking system in addition to logging.",
              file: m.file,
              line: m.line,
              fix: "Add error reporting alongside logging: `Sentry.captureException(err)` or equivalent.",
            });
          }
        }
      },
    },
  },
} satisfies RuleSet;