{"record":{"id":"cbc0f54207a34346","repo":"filamentphp/filament","slug":"the-automaticallyopenimageeditorforaspectratio-cbc0f5","errorCode":null,"errorMessage":"The [automaticallyOpenImageEditorForAspectRatio()] method cannot be used when [imageAspectRatio()] has multiple allowed aspect ratios.","messagePattern":"The \\[automaticallyOpenImageEditorForAspectRatio\\(\\)\\] method cannot be used when \\[imageAspectRatio\\(\\)\\] has multiple allowed aspect ratios\\.","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"packages/forms/src/Components/FileUpload.php","lineNumber":630,"sourceCode":"\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)) {\n            $ratio = $ratio[0] ?? null;\n        }\n\n        if (blank($ratio)) {","sourceCodeStart":612,"sourceCodeEnd":648,"githubUrl":"https://github.com/filamentphp/filament/blob/53483fa9340e4ec637985fe454ebb58afb92ea24/packages/forms/src/Components/FileUpload.php#L612-L648","documentation":"`imageAspectRatio()` accepts an array of allowed ratios for validation, but the auto-open editor can only enforce one target ratio. When `getImageAspectRatio()` returns an array with more than one entry and the auto-open flag is enabled, `shouldAutomaticallyOpenImageEditorForAspectRatio()` throws an InvalidArgumentException.","triggerScenarios":"`FileUpload::make('photo')->imageAspectRatio([16 / 9, 4 / 3])->automaticallyOpenImageEditorForAspectRatio()`.","commonSituations":"Relaxing a fixed ratio to multiple allowed ratios for flexibility while keeping the auto-open editor flag from the original config.","solutions":["Keep a single ratio: `->imageAspectRatio(16 / 9)`.","If multiple ratios must stay allowed, remove `automaticallyOpenImageEditorForAspectRatio()` and validate the ratio server-side instead."],"exampleFix":"// before\nFileUpload::make('photo')\n    ->imageAspectRatio([16 / 9, 4 / 3])\n    ->automaticallyOpenImageEditorForAspectRatio(),\n\n// after\nFileUpload::make('photo')\n    ->imageAspectRatio(16 / 9)\n    ->automaticallyOpenImageEditorForAspectRatio(),","handlingStrategy":"validation","validationCode":"$ratios = $config['aspect_ratios'] ?? [16 / 9];\n\nif ($autoOpenEditor && count($ratios) > 1) {\n    throw new InvalidArgumentException(\n        'automaticallyOpenImageEditorForAspectRatio requires exactly one allowed aspect ratio.'\n    );\n}\n\n$field->imageAspectRatio($autoOpenEditor ? $ratios[0] : $ratios);","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":["Keep auto-open presets pinned to a single scalar ratio.","If you relax to multiple ratios, drop the auto-open flag in the same commit.","Encode the ratio count constraint in your field-preset config validation."],"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"}