CatchCannotHandleKnownThrowable

warning native off by default

Group: Probable bugs

Identify a catch clause when its directly enclosing try consists of one explicit throw of a resolved Error subtype and every catch type excludes that subtype; exclude finally and calls that can throw another type.

Detection

• Report a catch clause when its directly enclosing try consists of one explicit throw of a resolved Error subtype and every catch type excludes that subtype; exclude finally and calls that can throw another type.
• D1a. The thrown object must be built by the builtin constructor from arguments whose evaluation cannot raise anything: integer, float and non-interpolated string literals, true, false, null, magic constants and plain variables, each optionally parenthesised. Any other argument expression discards the proof, including calls, match, property, offset and class-constant fetches, named constants, interpolation, concatenation, casts, arithmetic, clone, variable variables and argument unpacking.
• The builtin constructor can reject its arguments with TypeError or ArgumentCountError. Unless the argument list is empty or is exactly one positional string literal, a catch type that accepts either of those two classes counts as able to handle a throwable and no clause of that try is reported.
• Resolve builtin functions, classes, constants and methods, including imports and supported named arguments. Follow only bounded local facts within one lexical scope. Receiver and argument provenance must establish the specific API contract; variable names and comments never prove intent.
• Report one finding per violating operation. A reachable path, unchanged value identity and applicable API behavior are required. Intervening mutation, unknown calls involving tracked values or escaped aliases invalidate proof. When the proof is inconclusive, nothing is reported.

Exceptions (no report)

• Exclude unresolved required symbols, user-defined lookalikes, incomplete syntax, unknown required values and unsupported versions.
• No report when an argument of the thrown object falls outside the D1a list, for example new Error(match ($code) { 1 => 'one' }) caught as UnhandledMatchError, or new Error($record->label) and new Error("failed: $record") caught as Exception: a magic accessor or string conversion may throw the caught type first.
• No report for throw new Error($message) caught as TypeError: a non-string value makes the constructor itself throw the caught type.
• Both @custos-ignore CatchCannotHandleKnownThrowable and @noinspection CatchCannotHandleKnownThrowable suppress this native rule.

Fix

None. A repair requires a semantic decision or application error-handling policy.

PHP versions

Available in PHP 5.3–8.5 where the referenced API exists. Do not apply extension contracts when the resolved API is unavailable. Gate syntax and version-specific behavior to the configured target.

Configure

In custos.json:

{
  "rules": {
    "CatchCannotHandleKnownThrowable": {
      "enabled": true
    }
  }
}

Suppress

Before the statement or declaration (or the first statement of the file):

// @custos-ignore CatchCannotHandleKnownThrowable