# Common Error Types and Exceptions in Open Notebook (lfnovo/open-notebook)

> Explore common error types and exceptions in Open Notebook. Understand its twelve-class exception hierarchy and intelligent error classification for seamless database and AI integrations.

- Repository: [Luis Novo/open-notebook](https://github.com/lfnovo/open-notebook)
- Tags: how-to-guide
- Published: 2026-06-26

---

**Open Notebook defines a twelve-class exception hierarchy in [`open_notebook/exceptions.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/exceptions.py) that categorizes failures from database operations to external AI provider errors, complemented by an intelligent classification utility in [`open_notebook/utils/error_classifier.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/utils/error_classifier.py) that translates raw third-party exceptions into user-friendly domain-specific types.**

Open Notebook is a FastAPI-based application that orchestrates complex workflows between SurrealDB, LangGraph, and multiple LLM providers. Understanding the **common error types and exceptions in lfnovo/open-notebook** is critical for implementing robust error handling, debugging integration failures, and ensuring clean API responses. The codebase centralizes error management through a custom exception hierarchy rooted in `OpenNotebookError` and an intelligent classification system that maps external provider failures into predictable, catchable exception types.

## The Core Exception Hierarchy

All custom exceptions in Open Notebook inherit from `OpenNotebookError`, defined in [`open_notebook/exceptions.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/exceptions.py). This base class ensures consistent error handling across FastAPI endpoints, database repositories, and workflow engines.

### Database and Storage Errors

**`DatabaseOperationError`** signals failures during async SurrealDB operations. This exception triggers when connection pools are exhausted, query syntax is invalid, or transactions fail to commit. It appears frequently in repository layers that interact with the SurrealDB backend.

### Input Validation and Resource Errors

**`InvalidInputError`** handles malformed request payloads or missing required fields during API validation. **`NotFoundError`** indicates 404-style scenarios when requested resources—such as notebooks, sources, or notes—do not exist in the database. **`UnsupportedTypeException`** occurs when workflows receive incompatible data types, such as attempting to embed non-text payloads or processing unknown file formats.

### Authentication and Configuration Failures

**`AuthenticationError`** wraps credential check failures, including invalid API keys, missing authentication tokens, or provider-level access denials. **`ConfigurationError`** surfaces when the application detects misconfigurations in [`settings.yaml`](https://github.com/lfnovo/open-notebook/blob/main/settings.yaml) or missing environment variables required for model initialization.

### External Service and Network Errors

**`ExternalServiceError`** acts as a generic wrapper for failures originating from LLM providers, embedding APIs, or other third-party services, including HTTP 5xx responses and context-length violations. **`RateLimitError`** specifically handles 429 Too Many Requests responses and quota-exceeded messages from providers. **`NetworkError`** captures low-level connectivity issues such as DNS failures, connection timeouts, and refused ports.

### File and Media Processing Errors

**`FileOperationError`** indicates filesystem-related problems when reading or writing PDFs, audio files, or temporary cache data. **`NoTranscriptFound`** specifically handles cases where video ingestion workflows—particularly YouTube sources—encounter media lacking caption transcripts.

## Error Classification Utility

The `classify_error` function in [`open_notebook/utils/error_classifier.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/utils/error_classifier.py) inspects raw exceptions from LLM providers, LangChain, or HTTP clients and maps them onto the domain-specific hierarchy above. This utility implements keyword-based rules to determine the appropriate exception class:

- **Authentication** keywords → `AuthenticationError` with UI-friendly hints
- **Rate-limit** indicators → `RateLimitError`
- **Configuration** patterns (e.g., "model not found", "no model configured") → `ConfigurationError`
- **Network** timeouts or connection refused → `NetworkError`
- **Context-length** or payload-too-large errors → `ExternalServiceError`
- **Provider availability** (500-series errors) → `ExternalServiceError`

Unrecognized errors are logged internally and wrapped as `ExternalServiceError` to prevent internal stack traces from leaking to API consumers.

## Practical Implementation Examples

### Raising Domain-Specific Exceptions

Service layers raise typed exceptions to communicate specific failure modes to API routers:

```python
from open_notebook.exceptions import NotFoundError

async def get_notebook(notebook_id: str):
    notebook = await repo.fetch_notebook(notebook_id)
    if notebook is None:
        raise NotFoundError(f"Notebook {notebook_id} does not exist")
    return notebook

```

The FastAPI router catches `OpenNotebookError` subclasses and returns structured error payloads defined in [`api/models.py`](https://github.com/lfnovo/open-notebook/blob/main/api/models.py).

### Classifying Provider Errors in Workflows

Workflows use the classifier to translate raw provider exceptions into domain-specific types:

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

try:
    result = await some_llm_call(...)
except Exception as exc:
    exc_class, user_msg = classify_error(exc)
    raise exc_class(user_msg) from exc

```

This pattern converts an `httpx.HTTPStatusError` with "413 Payload Too Large" into an `ExternalServiceError` with a concise, user-friendly message.

### Global Exception Handling in FastAPI

The application registers a global handler in [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py) to ensure consistent error responses:

```python
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from open_notebook.exceptions import OpenNotebookError

app = FastAPI()

@app.exception_handler(OpenNotebookError)
async def open_notebook_error_handler(request: Request, exc: OpenNotebookError):
    return JSONResponse(
        status_code=400,
        content={"detail": str(exc), "type": exc.__class__.__name__},
    )

```

All custom exceptions bubble up to this handler, which returns the `ErrorResponse` Pydantic model defined in [`api/models.py`](https://github.com/lfnovo/open-notebook/blob/main/api/models.py).

## Summary

- Open Notebook defines **twelve domain-specific exceptions** in [`open_notebook/exceptions.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/exceptions.py), all inheriting from `OpenNotebookError`.
- **`DatabaseOperationError`**, **`NotFoundError`**, and **`InvalidInputError`** cover data layer and validation failures.
- **`AuthenticationError`** and **`ConfigurationError`** handle credential and setup issues.
- **`ExternalServiceError`**, **`RateLimitError`**, and **`NetworkError`** wrap third-party provider and connectivity problems.
- The **`classify_error`** utility in [`open_notebook/utils/error_classifier.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/utils/error_classifier.py) maps raw exceptions into typed errors using keyword-based detection rules.
- FastAPI routes use a global exception handler to return structured JSON responses based on the `ErrorResponse` Pydantic model in [`api/models.py`](https://github.com/lfnovo/open-notebook/blob/main/api/models.py).

## Frequently Asked Questions

### What is the base exception class in Open Notebook?

**`OpenNotebookError`** serves as the root class for all custom exceptions in the repository. Defined at line 1 of [`open_notebook/exceptions.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/exceptions.py), it ensures that FastAPI exception handlers can catch all domain-specific errors with a single handler while maintaining a consistent interface for error logging and user messaging.

### How does Open Notebook handle rate limit errors from LLM providers?

The **`classify_error`** utility detects rate-limit patterns (such as HTTP 429 responses or quota-exceeded messages) and raises **`RateLimitError`**. This specific exception type, defined in [`open_notebook/exceptions.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/exceptions.py), allows the API to return appropriate 429 status codes to clients and implement retry logic with exponential backoff in workflow layers.

### Where is the error classification logic implemented?

The classification logic resides in **[`open_notebook/utils/error_classifier.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/utils/error_classifier.py)**, specifically within the `classify_error` function. This module inspects exception messages and types from providers like OpenAI, Anthropic, or LangChain, then applies regex-based and keyword-matching rules to determine the appropriate Open Notebook exception class to raise.

### How are database errors distinguished from external service errors?

**`DatabaseOperationError`** specifically targets async SurrealDB failures such as connection losses or transaction rollbacks, while **`ExternalServiceError`** handles HTTP-level failures from LLM and embedding providers. The distinction allows operators to apply different alerting strategies: database errors typically indicate infrastructure issues requiring immediate attention, whereas external service errors may suggest provider outages or rate limiting that resolve with retry logic.