---
title: "Exceptions"
manual: "LLM Foundation"
version: "0.41"
permalink: "https://docs.typo3.org/permalink/netresearch/nr-llm:api-exceptions@0.41"
source: "Api/Exceptions.rst"
rendered: "2026-10-20T08:48:47+00:00"
---

# Exceptions {#api-exceptions}

-   **interface NrLlmExceptionInterface**

    -   *Fully qualified name:* `\Netresearch\NrLlm\Exception\NrLlmExceptionInterface`

    Marker interface implemented by errors generated by this extension
    on its public API surface — including the `fromArray()`
    normalisation errors of `ChatMessage` / `ToolSpec` /
    `ToolCall`. Catch this when an nr_llm-defined failure should take the
    same error path ([ADR-053](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-053@0.41)):

    ```
    try {
        $response = $this->llmManager->chatWithTools($messages, $tools);
    } catch (NrLlmExceptionInterface $e) {
        throw new MyDomainException($e->getMessage(), 0, $e);
    }

    ```

    This includes agent request validation, specialized service failures,
    delegated credential validation and internally generated runtime or
    configuration errors. Native parent catches remain compatible.
    Exceptions originating in a consumer callback or an external dependency
    are not automatically converted; PHP engine errors such as `TypeError`
    are also outside this marker contract.
    For example, the bundled streaming adapters propagate their original
    PSR-18 network exception without an adapter retry loop. Callers can
    handle `Psr\Http\Client\NetworkExceptionInterface` separately;
    see [Streaming support](https://docs.typo3.org/permalink/netresearch/nr-llm:developer-streaming@0.41) for the fallback boundary.

    Tool-loop approval and input suspensions carry resumable state. Handle
    `ToolApprovalRequiredException` and `ToolInputRequiredException`
    before a common marker catch when using the tool loop directly, so the
    suspension can be persisted and resumed.

-   **class RuntimeException**

    -   *Fully qualified name:* `\Netresearch\NrLlm\Exception\RuntimeException`

    An internally generated runtime failure. Extends PHP's
    `\RuntimeException` and implements `NrLlmExceptionInterface`.

-   **class LogicException**

    -   *Fully qualified name:* `\Netresearch\NrLlm\Exception\LogicException`

    An internally generated logic or configuration error. Extends PHP's
    `\LogicException` and implements `NrLlmExceptionInterface`.

-   **class ProviderException**

    -   *Fully qualified name:* `\Netresearch\NrLlm\Provider\Exception\ProviderException`

    Base exception for provider errors.

    -   **getProvider() : string**

        Get the provider that threw the exception.

-   **class ProviderConfigurationException**

    -   *Fully qualified name:* `\Netresearch\NrLlm\Provider\Exception\ProviderConfigurationException`

    Thrown when a provider is incorrectly
    configured.

    Extends
    [\\Netresearch\\NrLlm\\Provider\\Exception\\ProviderException](https://docs.typo3.org/permalink/netresearch/nr-llm:netresearch-nrllm-provider-exception-providerexception@0.41)

-   **class ProviderConnectionException**

    -   *Fully qualified name:* `\Netresearch\NrLlm\Provider\Exception\ProviderConnectionException`

    Thrown when a connection to the provider
    fails.

    Extends
    [\\Netresearch\\NrLlm\\Provider\\Exception\\ProviderException](https://docs.typo3.org/permalink/netresearch/nr-llm:netresearch-nrllm-provider-exception-providerexception@0.41)

-   **class ProviderResponseException**

    -   *Fully qualified name:* `\Netresearch\NrLlm\Provider\Exception\ProviderResponseException`

    Thrown when the provider returns an
    unexpected or error response.

    Extends
    [\\Netresearch\\NrLlm\\Provider\\Exception\\ProviderException](https://docs.typo3.org/permalink/netresearch/nr-llm:netresearch-nrllm-provider-exception-providerexception@0.41)

-   **class UnsupportedFeatureException**

    -   *Fully qualified name:* `\Netresearch\NrLlm\Provider\Exception\UnsupportedFeatureException`

    Thrown when a requested feature is not
    supported by the provider.

    Extends
    [\\Netresearch\\NrLlm\\Provider\\Exception\\ProviderException](https://docs.typo3.org/permalink/netresearch/nr-llm:netresearch-nrllm-provider-exception-providerexception@0.41)

-   **class InvalidArgumentException**

    -   *Fully qualified name:* `\Netresearch\NrLlm\Exception\InvalidArgumentException`

    Thrown for invalid method arguments.

-   **class ConfigurationNotFoundException**

    -   *Fully qualified name:* `\Netresearch\NrLlm\Exception\ConfigurationNotFoundException`

    Thrown when a named configuration is not found.

-   **class ConfigurationInactiveException**

    -   *Fully qualified name:* `\Netresearch\NrLlm\Exception\ConfigurationInactiveException`

    Thrown when a named configuration exists but is
    deactivated ([ADR-070](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-070@0.41)).

    Only `ConfigurationResolver::getActiveByIdentifier()` differentiates
    inactive from not-found; the user-aware
    `LlmConfigurationServiceInterface::getConfiguration()` signals the
    inactive case as `ConfigurationNotFoundException` (code `2690936773`).

## Planned request events {#api-exceptions-planned-request-events}

> [!NOTE]
> PSR-14 events (`BeforeRequestEvent`, `AfterResponseEvent`) are planned
> for a future release. The event classes do not exist yet in the current
> codebase.
>
> The existing editorial write event is documented in [Events](https://docs.typo3.org/permalink/netresearch/nr-llm:api-events@0.41).