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

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. 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. 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 and 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.

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 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}