filamentphp/filament · error · InvalidArgumentException

The [automaticallyOpenImageEditorForAspectRatio()] method ca

Error message

The [automaticallyOpenImageEditorForAspectRatio()] method cannot be used when [multiple()] is enabled.

What it means

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

Source

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

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

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

View on GitHub (pinned to 53483fa934)

Solutions

1. Remove `multiple()` if per-image aspect enforcement is required.
2. Keep `multiple()` and drop `automaticallyOpenImageEditorForAspectRatio()`, enforcing aspect ratios with validation rules instead.

Example fix

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

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

// In shared upload builders, enforce the invariant before configuring
if ($isMultiple && $shouldAutoOpenEditor) {
    throw new InvalidArgumentException(
        'automaticallyOpenImageEditorForAspectRatio cannot be combined with multiple().' 
    );
}

$field = FileUpload::make($name);

$isMultiple ? $field->multiple() : $field->automaticallyOpenImageEditorForAspectRatio();

function canAutoOpenEditorForAspectRatio(bool $isMultiple, string|float|array|null $ratio): bool
{
    return (! $isMultiple) && filled($ratio) && (! is_array($ratio) || count($ratio) === 1);
}

When it happens

Trigger: `FileUpload::make('photos')->multiple()->automaticallyOpenImageEditorForAspectRatio()`.

Common situations: 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.

Related errors

• The [automaticallyOpenImageEditorForAspectRatio()] method ca
• The [automaticallyOpenImageEditorForAspectRatio()] method re
• The file upload editor mode must be either 1, 2 or 3. [{$mod
• You cannot use the `disableToolbarButtons()` method when the
• You cannot use the `enableToolbarButtons()` method when the

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