>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3584344. --> Reported by: [marcus_johansson](https://www.drupal.org/user/385947) Related to !1482 >>> <p>[Tracker]<br> <strong>Update Summary: </strong>[One-line status update for stakeholders]<br> <strong>Short Description: </strong>The handleApiException signature change from Exception to Throwable breaks downstream providers (e.g. Anthropic) that override this method.<br> <strong>Check-in Date: </strong>MM/DD/YYYY<br> [/Tracker]</p> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-2"><a href="https://www.drupal.org/project/ai/issues/3573429" title="Status: Fixed">#3573429: Processing automators does not catch all errors</a></span> changed the signature of <code>handleApiException()</code> in <code>src/Base/OpenAiBasedProviderClientBase.php</code> from <code>\Exception</code> to <code>\Throwable</code>. See the diff at <a href="https://git.drupalcode.org/project/ai/-/commit/0dcf86740efce1774ade2ecaa7a1bf4ca31d37aa.diff">0dcf8674</a>.</p> <p>This was unintentionally a breaking change. Provider modules that extend <code>OpenAiBasedProviderClientBase</code> and override <code>handleApiException()</code> with the previous <code>\Exception</code> type hint are now incompatible with the parent signature and will fail with a PHP fatal error at class load. The Anthropic provider is a known affected consumer, and any third-party provider following the documented extension point is similarly broken.</p> <p>Widening a type hint on an overridden method in PHP is a Liskov-incompatible change for subclasses - subclasses must declare the same or broader type, so existing subclasses that used <code>\Exception</code> can no longer extend this base cleanly.</p> <h4 id="summary-steps-reproduce">Steps to reproduce (required for bugs, but not feature requests)</h4> <ol> <li>Install the AI module at the commit that introduced the change.</li> <li>Install any provider module that extends <code>OpenAiBasedProviderClientBase</code> and overrides <code>handleApiException()</code> with a <code>\Exception</code> parameter type (e.g. the Anthropic provider at its current released version).</li> <li>Trigger a provider class load and observe the PHP fatal error about incompatible method signatures.</li> </ol> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <ul> <li>Revert the <code>handleApiException()</code> parameter type on <code>OpenAiBasedProviderClientBase</code> from <code>\Throwable</code> back to <code>\Exception</code>.</li> <li>Keep the added logic that wraps PHP errors in <code>AiResponseErrorException</code>, but handle <code>\Error</code> separately at the call site (catch <code>\Error</code> in the surrounding try/catch block and wrap it before calling <code>handleApiException()</code>) rather than widening the handler's type hint.</li> <li>If the wider <code>\Throwable</code> behaviour is still wanted long term, reintroduce it as a new protected method (e.g. <code>handleApiThrowable()</code>) so that subclasses can opt in without having their overrides broken.</li> <li>Backport the revert to the affected branches so that provider modules can continue to extend the base class without hotfix releases.</li> <li>Add a test that constructs a subclass with <code>handleApiException(\Exception $e)</code> to guard against future signature widenings.</li> </ul> <h3 id="summary-ai-usage">AI usage (if applicable)</h3> <p>[x] AI Assisted Issue<br> This issue was generated with AI assistance, but was reviewed and refined by the creator.</p> <p>[ ] AI Assisted Code<br> [x] AI Generated Code<br> [ ] Vibe Coded</p> <p>- <strong>This issue was created with the help of AI</strong></p> > Related issue: [Issue #3573429](https://www.drupal.org/node/3573429)