{"record":{"id":"71d938d3f45235be","repo":"filamentphp/filament","slug":"the-automaticallyopenimageeditorforaspectratio","errorCode":null,"errorMessage":"The [automaticallyOpenImageEditorForAspectRatio()] method cannot be used when [multiple()] is enabled.","messagePattern":"The \\[automaticallyOpenImageEditorForAspectRatio\\(\\)\\] method cannot be used when \\[multiple\\(\\)\\] is enabled\\.","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"packages/forms/src/Components/FileUpload.php","lineNumber":620,"sourceCode":"\n    public function canEditSvgs(): bool\n    {\n        return (bool) $this->evaluate($this->canEditSvgs);\n    }\n\n    public function isSvgEditingConfirmed(): bool\n    {\n        return (bool) $this->evaluate($this->isSvgEditingConfirmed);\n    }\n\n    public function shouldAutomaticallyOpenImageEditorForAspectRatio(): bool\n    {\n        if (! $this->evaluate($this->shouldAutomaticallyOpenImageEditorForAspectRatio)) {\n            return false;\n        }\n\n        if ($this->isMultiple()) {\n            throw new InvalidArgumentException('The [automaticallyOpenImageEditorForAspectRatio()] method cannot be used when [multiple()] is enabled.');\n        }\n\n        $ratio = $this->getImageAspectRatio();\n\n        if (blank($ratio)) {\n            throw new InvalidArgumentException('The [automaticallyOpenImageEditorForAspectRatio()] method requires [imageAspectRatio()] to be set with a single aspect ratio.');\n        }\n\n        if (is_array($ratio) && count($ratio) > 1) {\n            throw new InvalidArgumentException('The [automaticallyOpenImageEditorForAspectRatio()] method cannot be used when [imageAspectRatio()] has multiple allowed aspect ratios.');\n        }\n\n        return true;\n    }\n\n    public function getAutomaticallyOpenImageEditorForAspectRatio(): ?float\n    {\n        if (! $this->shouldAutomaticallyOpenImageEditorForAspectRatio()) {","sourceCodeStart":602,"sourceCodeEnd":638,"githubUrl":"https://github.com/filamentphp/filament/blob/53483fa9340e4ec637985fe454ebb58afb92ea24/packages/forms/src/Components/FileUpload.php#L602-L638","documentation":"`automaticallyOpenImageEditorForAspectRatio()` opens the cropper when a single uploaded image does not match the configured ratio. With `multiple()` enabled there is no single 'the image' to enforce, so Filament throws an InvalidArgumentException inside `shouldAutomaticallyOpenImageEditorForAspectRatio()` — typically during render or upload handling.","triggerScenarios":"`FileUpload::make('photos')->multiple()->automaticallyOpenImageEditorForAspectRatio()`.","commonSituations":"A single-image avatar field that later gains `multiple()` during iteration, or a shared upload preset that hard-codes the auto-open behavior applied to gallery fields.","solutions":["Remove `multiple()` if per-image aspect enforcement is required.","Keep `multiple()` and drop `automaticallyOpenImageEditorForAspectRatio()`, enforcing aspect ratios with validation rules instead."],"exampleFix":"// before\nFileUpload::make('photos')\n    ->multiple()\n    ->automaticallyOpenImageEditorForAspectRatio(),\n\n// after\nFileUpload::make('avatar')\n    ->automaticallyOpenImageEditorForAspectRatio(),","handlingStrategy":"validation","validationCode":"// In shared upload builders, enforce the invariant before configuring\nif ($isMultiple && $shouldAutoOpenEditor) {\n    throw new InvalidArgumentException(\n        'automaticallyOpenImageEditorForAspectRatio cannot be combined with multiple().' \n    );\n}\n\n$field = FileUpload::make($name);\n\n$isMultiple ? $field->multiple() : $field->automaticallyOpenImageEditorForAspectRatio();","typeGuard":"function canAutoOpenEditorForAspectRatio(bool $isMultiple, string|float|array|null $ratio): bool\n{\n    return (! $isMultiple) && filled($ratio) && (! is_array($ratio) || count($ratio) === 1);\n}","tryCatchPattern":null,"preventionTips":["Treat auto-open as a single-upload feature; gate it behind an isMultiple() check in presets.","When a field gains multiple(), audit for aspect-ratio editor assumptions.","For galleries, enforce ratios with a validation rule instead."],"tags":["filament","file-upload","image-editor","aspect-ratio","configuration-conflict"],"backgroundTag":"mutually-exclusive-config","analyzedSha":"53483fa9340e4ec637985fe454ebb58afb92ea24","analyzedAt":"2026-08-17T02:06:23.049Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}