HKUDS/DeepTutor · error · HTTPException

File '{sanitized_filename}' exceeds maximum size limit of {s

Error message

File '{sanitized_filename}' exceeds maximum size limit of {size_str}

What it means

Raised while streaming an uploaded file to disk in _save_uploaded_files: the cumulative byte count exceeded the endpoint's max_size limit, so the write is aborted mid-stream with HTTP 400. The limit is formatted human-readably in the message.

Source

Thrown at deeptutor/api/routers/knowledge.py:433

                            except Exception as pb_exc:
                                logger.debug(
                                    "PocketBase file upload failed for '%s': %s",
                                    dest.name,
                                    pb_exc,
                                )
                    continue

                file_path = dest_dir / sanitized_filename
                max_size = DocumentValidator.MAX_FILE_SIZE
                written_bytes = 0

                file.file.seek(0)
                with open(file_path, "wb") as buffer:
                    for chunk in iter(lambda: file.file.read(8192), b""):
                        written_bytes += len(chunk)
                        if written_bytes > max_size:
                            size_str = format_bytes_human_readable(max_size)
                            raise HTTPException(
                                status_code=400,
                                detail=(
                                    f"File '{sanitized_filename}' exceeds maximum size "
                                    f"limit of {size_str}"
                                ),
                            )
                        buffer.write(chunk)

                DocumentValidator.validate_upload_safety(
                    sanitized_filename, written_bytes, allowed_extensions=allowed_extensions
                )
                written_file_paths.append(file_path)
                uploaded_files.append(rel_name)
                uploaded_file_paths.append(str(file_path))

                # Mirror file to PocketBase when enabled (best-effort, non-blocking).
                if _pb_sync and kb_name:
                    try:

View on GitHub (pinned to 3e82f13042)

Solutions

Compress, split, or trim the file below the configured max size
Raise the upload size limit in the server settings if the deployment allows it
For documents, export a lighter version (fewer pages/images) and retry

Example fix

# before
upload('huge_scan.pdf')  # 800MB
# after
upload('huge_scan_compressed.pdf')  # < limit

Defensive patterns

Strategy: validation

Validate before calling

import os

def under_limit(path, max_size):
    return os.path.getsize(path) <= max_size

Prevention

Check file size against the configured cap before upload
Compress or split large documents
Surface the server's limit in the UI so users know the cap

When it happens

Trigger: Uploading any file (or zip member landing via _save_uploaded_files) whose size exceeds the configured upload cap; the check fires mid-copy after 8192-byte chunks, so files only slightly over the limit still trigger it.

Common situations: Large PDFs/videos pushed to a KB with a conservative cap; zip members extracted after upload that individually exceed the limit; default limits not raised after increasing server disk.

Related errors

AI-assisted analysis of HKUDS/DeepTutor@3e82f13042 (2026-08-27). Data as JSON: /api/errors/4366cd168e2c465d. Report an issue: GitHub.