filamentphp/filament · error · InvalidArgumentException

The file upload editor mode must be either 1, 2 or 3. [{$mod

Error message

The file upload editor mode must be either 1, 2 or 3. [{$mode}] given, which is unsupported. See https://github.com/fengyuanchen/cropperjs/blob/v1/README.md#viewmode for more information on the available modes. Mode 0 is not supported, as it does not allow configuration via manual inputs.

What it means

FileUpload's image editor is powered by cropperjs v1's `viewMode`, and Filament only accepts 1, 2, or 3. Mode 0 is explicitly rejected because an unconstrained crop box cannot be represented in the editor's manual numeric inputs (offset/size), which Filament uses to make cropping keyboard-accessible. `imageEditorMode()` validates eagerly, so the InvalidArgumentException fires at configuration time.

Source

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

    public function imageEditorViewportWidth(int | Closure | null $width): static
    {
        $this->imageEditorViewportWidth = $width;

        return $this;
    }

    public function imageEditorViewportHeight(int | Closure | null $height): static
    {
        $this->imageEditorViewportHeight = $height;

        return $this;
    }

    public function imageEditorMode(int $mode): static
    {
        if (! in_array($mode, [1, 2, 3])) {
            throw new InvalidArgumentException("The file upload editor mode must be either 1, 2 or 3. [{$mode}] given, which is unsupported. See https://github.com/fengyuanchen/cropperjs/blob/v1/README.md#viewmode for more information on the available modes. Mode 0 is not supported, as it does not allow configuration via manual inputs.");
        }

        $this->imageEditorMode = $mode;

        return $this;
    }

    public function imageEditorEmptyFillColor(string | Closure | null $color): static
    {
        $this->imageEditorEmptyFillColor = $color;

        return $this;
    }

    /**
     * @param  array<string | null> | Closure  $ratios
     */
    public function imageEditorAspectRatioOptions(array | Closure $ratios): static

View on GitHub (pinned to 53483fa934)

Solutions

1. Choose a supported mode: `->imageEditorMode(1)` restricts the crop box to the canvas; 2 and 3 add stricter constraints.
2. When migrating a cropperjs config, map `viewMode: 0` to `1`.

Example fix

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

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

$mode = $config['image_editor_mode'] ?? 1;

if (! in_array($mode, [1, 2, 3], true)) {
    throw new InvalidArgumentException("imageEditorMode must be 1, 2 or 3; got [{$mode}].");
}

$field->imageEditorMode($mode);

function isSupportedImageEditorMode(int $mode): bool
{
    return in_array($mode, [1, 2, 3], true);
}

When it happens

Trigger: Calling `->imageEditorMode(0)` or `->imageEditorMode(4)` (any int outside 1–3) on a FileUpload field.

Common situations: Porting a cropperjs config from another app where `viewMode: 0` is the default, or copying values from cropperjs docs rather than Filament's.

Related errors

• The [automaticallyOpenImageEditorForAspectRatio()] method ca
• The [automaticallyOpenImageEditorForAspectRatio()] method re
• The [automaticallyOpenImageEditorForAspectRatio()] method ca
• No [{$userClass}] model found. Please bind an authenticatabl
• Import column of class [$importColumnClass] must have a uniq

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