{"record":{"id":"0072fd7c82583ed3","repo":"filamentphp/filament","slug":"the-automaticallyopenimageeditorforaspectratio-0072fd","errorCode":null,"errorMessage":"The [automaticallyOpenImageEditorForAspectRatio()] method requires [imageAspectRatio()] to be set with a single aspect ratio.","messagePattern":"The \\[automaticallyOpenImageEditorForAspectRatio\\(\\)\\] method requires \\[imageAspectRatio\\(\\)\\] to be set with a single aspect ratio\\.","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"packages/forms/src/Components/FileUpload.php","lineNumber":626,"sourceCode":"    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()) {\n            return null;\n        }\n\n        $ratio = $this->getImageAspectRatio();\n\n        if (is_array($ratio)) {","sourceCodeStart":608,"sourceCodeEnd":644,"githubUrl":"https://github.com/filamentphp/filament/blob/53483fa9340e4ec637985fe454ebb58afb92ea24/packages/forms/src/Components/FileUpload.php#L608-L644","documentation":"The auto-open image editor needs a target ratio to compare the uploaded image against. `shouldAutomaticallyOpenImageEditorForAspectRatio()` evaluates `getImageAspectRatio()` and throws an InvalidArgumentException when it is blank, because there is nothing to enforce or open the editor for.","triggerScenarios":"`FileUpload::make('avatar')->automaticallyOpenImageEditorForAspectRatio()` with no `imageAspectRatio()` set anywhere on the field.","commonSituations":"Enabling the behavior from a preset/helper that forgets the ratio, or removing `imageAspectRatio()` during a refactor while keeping the auto-open flag.","solutions":["Set a single ratio before enabling: `->imageAspectRatio(16 / 9)`.","Remove `automaticallyOpenImageEditorForAspectRatio()` if no ratio actually applies to the field."],"exampleFix":"// before\nFileUpload::make('avatar')\n    ->automaticallyOpenImageEditorForAspectRatio(),\n\n// after\nFileUpload::make('avatar')\n    ->imageAspectRatio(16 / 9)\n    ->automaticallyOpenImageEditorForAspectRatio(),","handlingStrategy":"validation","validationCode":"// In shared upload builders, enforce the invariant before configuring\nif ($shouldAutoOpenEditor && blank($aspectRatio)) {\n    throw new InvalidArgumentException(\n        'automaticallyOpenImageEditorForAspectRatio requires imageAspectRatio() to be set.'\n    );\n}\n\n$field = FileUpload::make($name)\n    ->imageAspectRatio($aspectRatio)\n    ->automaticallyOpenImageEditorForAspectRatio();","typeGuard":"function hasSingleAspectRatio(FileUpload $field): bool\n{\n    $ratio = $field->getImageAspectRatio();\n\n    return filled($ratio) && (! is_array($ratio) || count($ratio) === 1);\n}","tryCatchPattern":null,"preventionTips":["Always pair the auto-open flag with an imageAspectRatio() call in presets.","When removing imageAspectRatio(), grep for dependent editor flags.","Add a unit test asserting your preset fields pass shouldAutomaticallyOpenImageEditorForAspectRatio() cleanly."],"tags":["filament","file-upload","image-editor","aspect-ratio","missing-configuration"],"backgroundTag":"missing-required-configuration","analyzedSha":"53483fa9340e4ec637985fe454ebb58afb92ea24","analyzedAt":"2026-08-17T02:06:23.049Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}