crewAIInc/crewAI · error · FileValidationError

Image '{filename}' width ({width}px) exceeds maximum ({const

Error message

Image '{filename}' width ({width}px) exceeds maximum ({constraints.max_width}px)

What it means

validate_image parses the image header for dimensions and raises FileValidationError when width > constraints.max_width (message includes actual and allowed pixel values). It only fires if dimension probing succeeds (_get_image_dimensions returns data) and max_width is set; with raise_on_error=True (default) the first violated dimension aborts.

Source

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

        file.content_type,
        constraints.supported_formats,
        errors,
        raise_on_error,
    )

    if constraints.max_width is not None or constraints.max_height is not None:
        dimensions = _get_image_dimensions(content)
        if dimensions is not None:
            width, height = dimensions

            if constraints.max_width and width > constraints.max_width:
                msg = (
                    f"Image '{filename}' width ({width}px) exceeds "
                    f"maximum ({constraints.max_width}px)"
                )
                errors.append(msg)
                if raise_on_error:
                    raise FileValidationError(msg, file_name=filename)

            if constraints.max_height and height > constraints.max_height:
                msg = (
                    f"Image '{filename}' height ({height}px) exceeds "
                    f"maximum ({constraints.max_height}px)"
                )
                errors.append(msg)
                if raise_on_error:
                    raise FileValidationError(msg, file_name=filename)

    return errors


def validate_pdf(
    file: PDFFile,
    constraints: PDFConstraints,
    *,
    raise_on_error: bool = True,

View on GitHub (pinned to 754d7323be)

Solutions

Enable FileHandling.AUTO so the processor resizes images to fit max_width/max_height (requires Pillow).
Resize upstream before validation (client-side or in an upload pipeline).
Raise max_width in constraints if the provider accepts larger images.
Catch FileValidationError and surface the pixel numbers to the uploader for self-service fixing.

Example fix

# before
constraints = ImageConstraints(max_width=2048)
validate_image(photo, constraints)  # FileValidationError: width 4032px exceeds maximum 2048px

# after
from crewai_files.processing.enums import FileHandling
processor = FileProcessor(constraints=constraints, handling=FileHandling.AUTO)
out = processor.process(photo)  # auto-resized to <=2048px wide

Defensive patterns

Strategy: validation

Validate before calling

from PIL import Image

with Image.open(io.BytesIO(content)) as img:
    if constraints.max_width and img.width > constraints.max_width:
        return resize_or_reject(file, img.size)

Try / catch

from crewai_files.processing.exceptions import FileValidationError

try:
    processor.process(img_file)
except FileValidationError as e:
    if "width" in str(e):
        img_file = downscale(img_file, max_width=constraints.max_width)
        return processor.process(img_file)  # retry once, or use AUTO mode
    raise

Prevention

Use FileHandling.AUTO so resizing happens automatically (with Pillow installed).
Resize uploads client-side to provider limits (e.g. 2048px).
Set max_width from the target provider's documented image limits.

When it happens

Trigger: Validating an image wider than max_width (e.g. 4032px phone photo against max_width=2048) via validate_image or FileProcessor in STRICT mode. Both dimensions are checked independently, so an image can also fail the subsequent height check.

Common situations: Modern camera/phone photos (4000px+) against provider-friendly limits (1024/2048px); screenshots on retina displays; constraints tuned for one integration applied globally; scanned images at high DPI.

Related errors

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