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

Open Notebook defines a twelve-class exception hierarchy in 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 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. 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 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 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:

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.

Classifying Provider Errors in Workflows

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

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 to ensure consistent error responses:

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.

Summary

• Open Notebook defines twelve domain-specific exceptions in 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 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.

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

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