filamentphp/filament · error · InvalidArgumentException

The [automaticallyOpenImageEditorForAspectRatio()] method ca

Error message

The [automaticallyOpenImageEditorForAspectRatio()] method cannot be used when [imageAspectRatio()] has multiple allowed aspect ratios.

What it means

`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.

Source

Thrown at packages/forms/src/Components/FileUpload.php:630

    public function shouldAutomaticallyOpenImageEditorForAspectRatio(): bool
    {
        if (! $this->evaluate($this->shouldAutomaticallyOpenImageEditorForAspectRatio)) {
            return false;
        }

        if ($this->isMultiple()) {
            throw new InvalidArgumentException('The [automaticallyOpenImageEditorForAspectRatio()] method cannot be used when [multiple()] is enabled.');
        }

        $ratio = $this->getImageAspectRatio();

        if (blank($ratio)) {
            throw new InvalidArgumentException('The [automaticallyOpenImageEditorForAspectRatio()] method requires [imageAspectRatio()] to be set with a single aspect ratio.');
        }

        if (is_array($ratio) && count($ratio) > 1) {
            throw new InvalidArgumentException('The [automaticallyOpenImageEditorForAspectRatio()] method cannot be used when [imageAspectRatio()] has multiple allowed aspect ratios.');
        }

        return true;
    }

    public function getAutomaticallyOpenImageEditorForAspectRatio(): ?float
    {
        if (! $this->shouldAutomaticallyOpenImageEditorForAspectRatio()) {
            return null;
        }

        $ratio = $this->getImageAspectRatio();

        if (is_array($ratio)) {
            $ratio = $ratio[0] ?? null;
        }

        if (blank($ratio)) {

View on GitHub (pinned to 53483fa934)

Solutions

Keep a single ratio: `->imageAspectRatio(16 / 9)`.
If multiple ratios must stay allowed, remove `automaticallyOpenImageEditorForAspectRatio()` and validate the ratio server-side instead.

Example fix

// before
FileUpload::make('photo')
    ->imageAspectRatio([16 / 9, 4 / 3])
    ->automaticallyOpenImageEditorForAspectRatio(),

// after
FileUpload::make('photo')
    ->imageAspectRatio(16 / 9)
    ->automaticallyOpenImageEditorForAspectRatio(),

Defensive patterns

Strategy: validation

Validate before calling

$ratios = $config['aspect_ratios'] ?? [16 / 9];

if ($autoOpenEditor && count($ratios) > 1) {
    throw new InvalidArgumentException(
        'automaticallyOpenImageEditorForAspectRatio requires exactly one allowed aspect ratio.'
    );
}

$field->imageAspectRatio($autoOpenEditor ? $ratios[0] : $ratios);

Type guard

function hasSingleAspectRatio(FileUpload $field): bool
{
    $ratio = $field->getImageAspectRatio();

    return filled($ratio) && (! is_array($ratio) || count($ratio) === 1);
}

Prevention

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.

When it happens

Trigger: `FileUpload::make('photo')->imageAspectRatio([16 / 9, 4 / 3])->automaticallyOpenImageEditorForAspectRatio()`.

Common situations: Relaxing a fixed ratio to multiple allowed ratios for flexibility while keeping the auto-open editor flag from the original config.

Related errors

AI-assisted analysis of filamentphp/filament@53483fa934 (2026-08-17). Data as JSON: /api/errors/cbc0f54207a34346. Report an issue: GitHub.