# How open-notebook's error_classifier Maps LLM Exceptions to User-Friendly Messages

> Learn how open-notebook's error_classifier transforms LLM exceptions into clear messages. It maps raw AI provider errors to user-friendly OpenNotebookError types using keyword pattern matching.

- Repository: [Luis Novo/open-notebook](https://github.com/lfnovo/open-notebook)
- Tags: deep-dive
- Published: 2026-06-24

---

**The error_classifier in open-notebook converts raw AI provider exceptions into stable OpenNotebookError types using keyword-based pattern matching defined in `_CLASSIFICATION_RULES`, ensuring users see clear, actionable messages instead of technical tracebacks.**

The open-notebook repository centralizes error handling for LLM interactions through a dedicated classification system located in [`open_notebook/utils/error_classifier.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/utils/error_classifier.py). By intercepting provider-specific exceptions from libraries like Esperanto or LangChain and mapping them to standardized error types, the application delivers consistent feedback across different AI backends without exposing internal implementation details.

## Classification Rules and Pattern Matching

The mapping logic relies on a private list named `_CLASSIFICATION_RULES` defined at lines **[20‑69]** of [`open_notebook/utils/error_classifier.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/utils/error_classifier.py). Each entry contains case-insensitive keywords, a target exception class, and an optional user-facing message. The classifier searches for these keywords within the normalized exception text to determine the appropriate error type.

The current rule set covers seven distinct failure categories:

- **Authentication failures** – Keywords `authentication`, `unauthorized`, `invalid api key`, and `401` map to `AuthenticationError` with the message "Authentication failed …"
- **Rate limiting** – Keywords `rate limit`, `429`, `too many requests`, and `quota exceeded` map to `RateLimitError` with the message "Rate limit exceeded …"
- **Model configuration issues** – Keywords `model not found`, `does not exist`, `no model configured`, and `please go to settings` map to `ConfigurationError`, preserving the original exception text
- **Network connectivity problems** – Keywords `connecterror`, `timeoutexception`, `connection refused`, and `timeout` map to `NetworkError` with the message "Could not connect to the AI provider …"
- **Context length violations** – Keywords `context length`, `token limit`, and `max_tokens` map to `ExternalServiceError` with the message "Content too large for the selected model …"
- **Payload size errors** – Keywords `413` and `payload too large` map to `ExternalServiceError` with the message "The request payload is too large …"
- **Service outages** – Keywords `500`, `502`, `503`, and `service unavailable` map to `ExternalServiceError` with the message "The AI provider is temporarily unavailable …"

## The classify_error Algorithm

The public function `classify_error` (lines **[72‑96]**) implements the core normalization and matching logic. This function accepts any raw exception and returns a tuple containing the appropriate `OpenNotebookError` subclass and a sanitized message string.

### Normalization and Keyword Matching

The algorithm first normalizes the exception by lowercasing both its string representation and its type name, then concatenating them into a single searchable string. It iterates through `_CLASSIFICATION_RULES` in order, checking whether any keyword from a rule appears in the combined text. The first match wins immediately, returning the associated exception class and message.

When a rule specifies `None` for the user message (as with configuration errors), the classifier invokes the `_truncate` helper (lines **[99‑104]**) to shorten the original exception text before returning it.

### Fallback Handling for Unknown Errors

If no classification rule matches the normalized exception, the function logs a warning via `logger.warning` (lines **[93‑95]**) and returns a generic `ExternalServiceError` paired with a truncated version of the original message. This ensures the application never propagates unhandled provider-specific exceptions to the UI layer.

## Integration with LLM Service Wrappers

Provider wrappers in `open_notebook/ai/` (such as [`provider_service.py`](https://github.com/lfnovo/open-notebook/blob/main/provider_service.py) and [`esperanto_wrapper.py`](https://github.com/lfnovo/open-notebook/blob/main/esperanto_wrapper.py)) act as the integration point for the error_classifier. These wrappers catch any exception raised during LLM calls, pass it to `classify_error`, and then raise the standardized `OpenNotebookError` to upstream code.

```python
from open_notebook.utils.error_classifier import classify_error
from open_notebook.exceptions import OpenNotebookError

def call_llm(provider, prompt):
    try:
        # This call may raise a provider‑specific exception

        return provider.generate(prompt)
    except Exception as exc:
        # Convert to a friendly OpenNotebookError

        exc_class, user_msg = classify_error(exc)
        raise exc_class(user_msg) from exc

# Example usage

try:
    answer = call_llm(my_openai_client, "Summarize this text")
except OpenNotebookError as e:
    # UI can show e.message to the user

    print(f"Error: {e}")

```

When an OpenAI client raises a rate limit error containing "429", the classifier matches the corresponding keyword and returns `RateLimitError` with the predefined friendly text. Front-end components can then inspect the exception class to determine appropriate UI feedback, such as prompting for credential re-entry when encountering an `AuthenticationError`.

## Summary

- The `_CLASSIFICATION_RULES` table in [`open_notebook/utils/error_classifier.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/utils/error_classifier.py) maps keywords like "401" or "rate limit" to specific `OpenNotebookError` subclasses including `AuthenticationError`, `RateLimitError`, and `NetworkError`.
- The `classify_error` function normalizes exception text via lowercasing and concatenation, returning the first matching rule or falling back to `ExternalServiceError` for unmatched cases.
- Configuration errors preserve original messages via the `_truncate` helper, while other error types return predefined user-friendly strings to ensure clarity.
- Provider wrappers in the AI layer catch raw exceptions and delegate classification to ensure UI components receive standardized error types rather than provider-specific tracebacks.

## Frequently Asked Questions

### What exception types does error_classifier return?

The function returns subclasses of `OpenNotebookError` defined in [`open_notebook/exceptions.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/exceptions.py), including `AuthenticationError`, `RateLimitError`, `ConfigurationError`, `NetworkError`, and `ExternalServiceError`. Each type corresponds to a specific failure mode in LLM interactions, allowing the UI to render appropriate feedback based on the error category.

### How does the classifier handle API authentication failures?

It searches the normalized exception text for keywords such as "authentication", "unauthorized", "invalid api key", or "401" and returns an `AuthenticationError` with the message "Authentication failed …". This pattern matching operates case-insensitively to ensure compatibility with various AI provider libraries.

### Where does open-notebook catch LLM exceptions for classification?

Provider-specific wrappers in the `open_notebook/ai/` directory intercept raw exceptions from underlying libraries like Esperanto or LangChain. These wrappers call `classify_error` before re-raising the exception as a standardized `OpenNotebookError`, ensuring consistent error handling across different AI backends.

### What happens when an error doesn't match any classification rule?

The classifier logs a warning message and returns a generic `ExternalServiceError` with a truncated version of the original exception text. This fallback mechanism ensures the application never exposes raw provider tracebacks to end users while still capturing the error details in logs for debugging purposes.