{"record":{"id":"8d30920e7c03198b","repo":"crewAIInc/crewAI","slug":"image-filename-width-width-px-exceeds-maxim","errorCode":null,"errorMessage":"Image '{filename}' width ({width}px) exceeds maximum ({constraints.max_width}px)","messagePattern":"Image '(.+?)' width \\((.+?)px\\) exceeds maximum \\((.+?)px\\)","errorType":"validation","errorClass":"FileValidationError","httpStatus":null,"severity":"error","filePath":"lib/crewai-files/src/crewai_files/processing/validators.py","lineNumber":274,"sourceCode":"        file.content_type,\n        constraints.supported_formats,\n        errors,\n        raise_on_error,\n    )\n\n    if constraints.max_width is not None or constraints.max_height is not None:\n        dimensions = _get_image_dimensions(content)\n        if dimensions is not None:\n            width, height = dimensions\n\n            if constraints.max_width and width > constraints.max_width:\n                msg = (\n                    f\"Image '{filename}' width ({width}px) exceeds \"\n                    f\"maximum ({constraints.max_width}px)\"\n                )\n                errors.append(msg)\n                if raise_on_error:\n                    raise FileValidationError(msg, file_name=filename)\n\n            if constraints.max_height and height > constraints.max_height:\n                msg = (\n                    f\"Image '{filename}' height ({height}px) exceeds \"\n                    f\"maximum ({constraints.max_height}px)\"\n                )\n                errors.append(msg)\n                if raise_on_error:\n                    raise FileValidationError(msg, file_name=filename)\n\n    return errors\n\n\ndef validate_pdf(\n    file: PDFFile,\n    constraints: PDFConstraints,\n    *,\n    raise_on_error: bool = True,","sourceCodeStart":256,"sourceCodeEnd":292,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/crewai-files/src/crewai_files/processing/validators.py#L256-L292","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nconstraints = ImageConstraints(max_width=2048)\nvalidate_image(photo, constraints)  # FileValidationError: width 4032px exceeds maximum 2048px\n\n# after\nfrom crewai_files.processing.enums import FileHandling\nprocessor = FileProcessor(constraints=constraints, handling=FileHandling.AUTO)\nout = processor.process(photo)  # auto-resized to <=2048px wide","handlingStrategy":"validation","validationCode":"from PIL import Image\n\nwith Image.open(io.BytesIO(content)) as img:\n    if constraints.max_width and img.width > constraints.max_width:\n        return resize_or_reject(file, img.size)","typeGuard":null,"tryCatchPattern":"from crewai_files.processing.exceptions import FileValidationError\n\ntry:\n    processor.process(img_file)\nexcept FileValidationError as e:\n    if \"width\" in str(e):\n        img_file = downscale(img_file, max_width=constraints.max_width)\n        return processor.process(img_file)  # retry once, or use AUTO mode\n    raise","preventionTips":["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."],"tags":["validation","image","dimensions","constraints","resize"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}