How to Fix 413 Payload Too Large Errors During File Uploads in Open Notebook

A 413 Payload Too Large error occurs when an uploaded file exceeds the server's configured request body limit, triggering FastAPI's exception handling pipeline before the file reaches the save_uploaded_file() function in Open Notebook.

When working with the Open Notebook project (lfnovo/open-notebook), users encounter 413 Payload Too Large errors during document uploads when the request size surpasses infrastructure limits. This error originates from multiple layers in the upload stack, including FastAPI's request parsing, reverse proxy configurations, and downstream AI provider constraints.

Root Causes of 413 Payload Too Large Errors

Understanding where size limits are enforced helps identify the correct fix. The error can originate from three distinct layers in the Open Notebook architecture.

FastAPI and Starlette Request Limits

The error first surfaces when the incoming request body exceeds Starlette's default size constraints. In api/main.py (lines 200-206), a custom exception handler catches the StarletteHTTPException with status code 413 immediately upon receipt, before the request ever reaches the POST /sources endpoint or the save_uploaded_file() function.

Reverse Proxy Restrictions

Upstream reverse proxies like nginx or Traefik often enforce their own client_max_body_size limits. When these proxies intercept a large file upload, they terminate the request with a 413 error before it reaches the FastAPI application, as documented in the handler comments at lines 206-208 of api/main.py.

AI Provider Context Window Limits

After successful upload via save_uploaded_file() in api/routers/sources.py (lines 88-100), subsequent processing may trigger a 413 equivalent when sending content to AI providers. The error classification utility in open_notebook/utils/error_classifier.py (lines 57-62) treats these as payload-too-large scenarios when the content exceeds model context windows.

How Open Notebook Handles 413 Errors

The application implements a multi-tier handling strategy to detect, classify, and report oversized payloads.

Exception Interception with CORS Headers

The custom handler in api/main.py (lines 200-206) catches StarletteHTTPException instances with status 413 and returns JSON responses with proper CORS headers. This prevents the client from receiving generic HTML error pages and ensures the browser can read the error response.

Error Classification Mapping

The utility in open_notebook/utils/error_classifier.py (lines 57-62) maps keywords including "413", "payload too large", and "request entity too large" to an ExternalServiceError with the user-friendly message: "The request payload is too large for the AI provider. Try reducing the content size or using a different model."

File Storage Flow

The save_uploaded_file() function in api/routers/sources.py (lines 88-100) writes uploaded bytes to UPLOADS_FOLDER, but only executes if the request successfully passes the initial size validation at the Starlette layer.

Solutions for 413 Payload Too Large Errors

Resolving these errors requires configuration changes at the appropriate infrastructure layer.

Increase Server Body Size Limits

Configure the Uvicorn server or FastAPI application to accept larger payloads by adjusting the --limit-max-body-size parameter or equivalent Starlette configuration. This allows the POST /sources endpoint to receive files that would otherwise trigger the 413 error at the application server level.

Configure Reverse Proxy Settings

For nginx, increase the client_max_body_size directive in your configuration file:

# /etc/nginx/nginx.conf

http {
    client_max_body_size 50M;  # allow up to 50 MiB uploads

}

For Traefik, adjust the http.max_body_size setting to match your application's expected maximum file size.

Implement Client-Side Validation

Prevent oversized uploads before they reach the server by validating file sizes in the client application:

# Example: Raising a custom 413 error manually (e.g., after detecting a huge file)

from fastapi import HTTPException

if uploaded_file_size > MAX_UPLOAD_BYTES:
    raise HTTPException(
        status_code=413,
        detail="Payload Too Large: uploaded file exceeds the permitted size."
    )

Handle AI Provider Limits

When processing large files for AI embedding or analysis, use the built-in error classifier to produce user-friendly messages:

# Example: Using the built-in error classifier to produce a user-friendly message

from open_notebook.utils.error_classifier import classify_error

try:
    await external_ai_call(payload)
except Exception as exc:
    exc_type, friendly_msg = classify_error(exc)
    raise exc_type(friendly_msg) from exc

Summary

• FastAPI/Starlette raises 413 errors when request bodies exceed configured limits, handled in api/main.py (lines 200-206) with custom CORS-enabled JSON responses.
• Reverse proxies like nginx may block large uploads before they reach the application, requiring client_max_body_size adjustments.
• AI provider limits are classified by open_notebook/utils/error_classifier.py (lines 57-62) as external service errors with actionable user messages.
• File storage via save_uploaded_file() in api/routers/sources.py (lines 88-100) only occurs after successful request size validation.

Frequently Asked Questions

How do I increase the upload size limit in Open Notebook?

You must increase the limit at both the reverse proxy and application server levels. Configure client_max_body_size in nginx or http.max_body_size in Traefik, and ensure your Uvicorn or ASGI server allows the corresponding body size. According to the source code in api/main.py, these limits are checked before the file reaches the save_uploaded_file() function.

Why does Open Notebook show a 413 error even for small files?

If small files trigger 413 errors, the limit is likely enforced by an upstream reverse proxy or the AI provider's API, not the Open Notebook server itself. Check the error classification in open_notebook/utils/error_classifier.py (lines 57-62) to determine if the error originates from an external service rather than the file upload handler.

Can I customize the error message for oversized uploads?

Yes. The error_classifier.py utility (lines 57-62) maps specific keywords to custom error types. You can modify the classification rules to return different ExternalServiceError messages, or implement custom validation in api/routers/sources.py before calling save_uploaded_file() to raise bespoke HTTPException instances with status 413.

What is the default file size limit in Open Notebook?

The default limit depends on your deployment configuration. Starlette and Uvicorn typically default to 1 MiB unless configured otherwise, while reverse proxies often have their own defaults (commonly 1-10 MiB). The actual enforcement occurs before the request reaches the save_uploaded_file() function in api/routers/sources.py (lines 88-100).

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