crewAIInc/crewAI · error · FileValidationError

Image '{filename}' height ({height}px) exceeds maximum ({con

Error message

Image '{filename}' height ({height}px) exceeds maximum ({constraints.max_height}px)

What it means

The second dimension check in validate_image: raises FileValidationError when height > constraints.max_height, with actual and maximum pixel counts in the message. Evaluated after the width check on the same probed dimensions; only reached when the width check passed (or its raise_on_error was False).

Source

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

            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,
) -> Sequence[str]:
    """Validate a PDF file against constraints.

    Args:
        file: The PDF file to validate.
        constraints: PDF constraints to validate against.
        raise_on_error: If True, raise exceptions on validation failure.

    Returns:

View on GitHub (pinned to 754d7323be)

Solutions

Enable FileHandling.AUTO to let the processor resize within max_width/max_height bounds (aspect ratio preserved).
Split tall screenshots into segments upstream before attaching.
Raise max_height to match real content (e.g. 4096 for full-page captures).
Check image.size yourself before validation and reject/resize with a custom message.

Example fix

# before
constraints = ImageConstraints(max_height=1280)
validate_image(screenshot, constraints)  # FileValidationError: height 3600px exceeds maximum 1280px

# after
from crewai_files.processing.enums import FileHandling
processor = FileProcessor(constraints=constraints, handling=FileHandling.AUTO)
out = processor.process(screenshot)  # resized to fit height limit

Defensive patterns

Strategy: validation

Validate before calling

from PIL import Image

with Image.open(io.BytesIO(content)) as img:
    if constraints.max_height and img.height > constraints.max_height:
        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 "height" in str(e):
        img_file = fit_within(img_file, max_height=constraints.max_height)
        return processor.process(img_file)
    raise

Prevention

Check both dimensions before attaching; tall screenshots are the usual failure.
Enable AUTO mode to resize within bounds while preserving aspect ratio.
Split very tall captures into multiple images upstream.

When it happens

Trigger: Validating an image taller than max_height (e.g. a 3000px-tall screenshot against max_height=1280) via validate_image or STRICT-mode processing. Tall screenshots, panoramic stitches, and long vertical captures are the usual offenders.

Common situations: Full-page screenshots and chat captures that are narrow but very tall; poster/infographic uploads; aspect-ratio-unaware limits set per dimension.

Related errors

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