crewAIInc/crewAI · error · FileTooLargeError

{file_type} '{filename}' size ({_format_size(file_size)}) ex

Error message

{file_type} '{filename}' size ({_format_size(file_size)}) exceeds maximum ({_format_size(max_size)})

What it means

The shared size validator _validate_size (used by validate_image/validate_pdf/validate_audio/validate_video) raises FileTooLargeError when file_size > max_size. The exception carries structured fields: file_name, actual_size and max_size, and the message renders human-readable sizes via _format_size (e.g. 'Image "photo.png" size (8.0MB) exceeds maximum (5.0MB)'). In non-strict calls the message is only appended to the errors list.

Source

Thrown at lib/crewai-files/src/crewai_files/processing/validators.py:186

) -> None:
    """Validate file size against maximum.

    Args:
        file_type: Type label for error messages (e.g., "Image", "PDF").
        filename: Name of the file being validated.
        file_size: Actual file size in bytes.
        max_size: Maximum allowed size in bytes.
        errors: List to append error messages to.
        raise_on_error: If True, raise FileTooLargeError on failure.
    """
    if file_size > max_size:
        msg = (
            f"{file_type} '{filename}' size ({_format_size(file_size)}) exceeds "
            f"maximum ({_format_size(max_size)})"
        )
        errors.append(msg)
        if raise_on_error:
            raise FileTooLargeError(
                msg,
                file_name=filename,
                actual_size=file_size,
                max_size=max_size,
            )


def _validate_format(
    file_type: str,
    filename: str | None,
    content_type: str,
    supported_formats: tuple[str, ...],
    errors: list[str],
    raise_on_error: bool,
) -> None:
    """Validate content type against supported formats.

    Args:

View on GitHub (pinned to 754d7323be)

Solutions

1. Use the structured fields (e.actual_size vs e.max_size) to give the user a precise message and reject or compress.
2. Enable FileHandling.AUTO so oversized images are compressed (optimize_image) instead of rejected.
3. Raise max_size_bytes if the provider actually permits larger payloads.
4. For PDFs, use FileHandling.CHUNK to split by pages instead of failing on total size.

Example fix

# before
constraints = ImageConstraints(max_size_bytes=5 * 1024 * 1024)
errors = validate_image(img, constraints)  # FileTooLargeError for 8MB image

# after
from crewai_files.processing.enums import FileHandling
processor = FileProcessor(constraints=constraints, handling=FileHandling.AUTO)
out = processor.process(img)  # compressed under the limit instead of raising

size = len(content)
if constraints.max_size_bytes is not None and size > constraints.max_size_bytes:
    return reject_or_compress(file, size, constraints.max_size_bytes)

from crewai_files.processing.exceptions import FileTooLargeError

try:
    processor.process(file)
except FileTooLargeError as e:
    msg = f"'{e.file_name}' is {_fmt(e.actual_size)}; limit is {_fmt(e.max_size)}"
    return reject_upload(msg)

When it happens

Trigger: Validating any file whose byte size exceeds the constraint's max_size_bytes (e.g. ImageConstraints(max_size_bytes=5MB) with a 8MB upload) with raise_on_error=True (the default). Also reached via FileProcessor in STRICT mode after validate() collects the error.

Common situations: Provider hard limits (e.g. Anthropic/OpenAI request size caps) encoded as constraints, hit by high-resolution photos or scanned PDFs; user uploads from mobile cameras; constraints copied between projects with tighter limits than intended.

Related errors

• File exceeds max size ({actual_size} > {self.max_size_bytes}
• "; ".join(errors)
• {file_type} format '{content_type}' is not supported. Suppor
• Image '{filename}' width ({width}px) exceeds maximum ({const
• Image '{filename}' height ({height}px) exceeds maximum ({con

AI-assisted analysis of crewAIInc/crewAI@754d7323be (2026-08-15). Data as JSON: /api/errors/70192f6aa72ea96e. Report an issue: GitHub.