filamentphp/filament · error · InvalidArgumentException

The [automaticallyOpenImageEditorForAspectRatio()] method re

Error message

The [automaticallyOpenImageEditorForAspectRatio()] method requires [imageAspectRatio()] to be set with a single aspect ratio.

What it means

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.

Source

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

    public function isSvgEditingConfirmed(): bool
    {
        return (bool) $this->evaluate($this->isSvgEditingConfirmed);
    }

    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)) {

View on GitHub (pinned to 53483fa934)

Solutions

1. Set a single ratio before enabling: `->imageAspectRatio(16 / 9)`.
2. Remove `automaticallyOpenImageEditorForAspectRatio()` if no ratio actually applies to the field.

Example fix

// before
FileUpload::make('avatar')
    ->automaticallyOpenImageEditorForAspectRatio(),

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

// In shared upload builders, enforce the invariant before configuring
if ($shouldAutoOpenEditor && blank($aspectRatio)) {
    throw new InvalidArgumentException(
        'automaticallyOpenImageEditorForAspectRatio requires imageAspectRatio() to be set.'
    );
}

$field = FileUpload::make($name)
    ->imageAspectRatio($aspectRatio)
    ->automaticallyOpenImageEditorForAspectRatio();

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

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

When it happens

Trigger: `FileUpload::make('avatar')->automaticallyOpenImageEditorForAspectRatio()` with no `imageAspectRatio()` set anywhere on the field.

Common situations: Enabling the behavior from a preset/helper that forgets the ratio, or removing `imageAspectRatio()` during a refactor while keeping the auto-open flag.

Related errors

• The [automaticallyOpenImageEditorForAspectRatio()] method ca
• The [automaticallyOpenImageEditorForAspectRatio()] method ca
• The file upload editor mode must be either 1, 2 or 3. [{$mod
• The [tableConfiguration()] method must be set when using a [
• MorphToSelect type [{$this->getModel()}] must have a [titleA

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