Intervention/image · error · InvalidArgumentException

Unable to find file extension from empty string

Error message

Unable to find file extension from empty string

What it means

InvalidArgumentException from the FileExtensionEncoder constructor: an empty string '' is explicitly rejected because it cannot be mapped to any media type. Note the distinction - null is valid (the encoder then falls back to the image's origin file extension at encode time) and unknown non-empty strings throw NotSupportedException instead; only exactly '' hits this check.

Source

Thrown at src/Encoders/FileExtensionEncoder.php:34

{
    /**
     * Encoder options.
     *
     * @var array<int|string, mixed>
     */
    protected array $options = [];

    /**
     * Create new encoder instance to encode to format of given file extension.
     *
     * @param null|string|FileExtension $extension Target file extension for example "png"
     * @throws InvalidArgumentException
     * @throws NotSupportedException
     */
    public function __construct(public null|string|FileExtension $extension = null, mixed ...$options)
    {
        if ($extension === '') {
            throw new InvalidArgumentException('Unable to find file extension from empty string');
        }

        $mediaType = null;

        if (is_string($extension)) {
            try {
                $mediaType = FileExtension::from(strtolower($extension))->mediaType();
            } catch (Error) {
                throw new NotSupportedException(
                    'Unable to find encoder for unknown file extension "' . $extension . '"',
                );
            }
        }

        if ($extension instanceof FileExtension) {
            $mediaType = $extension->mediaType();
        }

View on GitHub (pinned to 5598b9e397)

Solutions

  1. Pass null instead of '' when the origin extension should be used: $ext = $ext ?: null
  2. Validate $extension !== '' before constructing the encoder
  3. Use the FileExtension enum (e.g. FileExtension::PNG) instead of raw strings when the target is known
  4. Reject or normalize extension-less filenames at the upload boundary

Example fix

// before
$ext = pathinfo($filename, PATHINFO_EXTENSION); // '' for 'photo'
$encoded = $image->encode(new FileExtensionEncoder($ext));

// after
$ext = pathinfo($filename, PATHINFO_EXTENSION) ?: null;
$encoded = $image->encode(new FileExtensionEncoder($ext));
Defensive patterns

Strategy: validation

Validate before calling

$extension = ($extension === '') ? null : $extension;
$encoded = $image->encode(new FileExtensionEncoder($extension));

Type guard

function isValidFileExtension(null|string|FileExtension $extension): bool
{
    return $extension === null || $extension instanceof FileExtension || $extension !== '';
}

Try / catch

use Intervention\Image\Exceptions\InvalidArgumentException as ImageInvalidArgumentException;

try {
    $encoder = new FileExtensionEncoder($extension);
} catch (ImageInvalidArgumentException $e) {
    $encoder = new FileExtensionEncoder(null); // fall back to origin extension
}

Prevention

When it happens

Trigger: new FileExtensionEncoder($ext) where $ext === '' - typically $ext = pathinfo($filename, PATHINFO_EXTENSION) on a filename without an extension, or an empty form field cast to string.

Common situations: Deriving the target format from user-supplied filenames that lack extensions; 'encode to same format as input' logic where the input name has no suffix; whitespace-only input trimmed to '' upstream.

Related errors

AI-assisted analysis of Intervention/image@5598b9e397 (2026-08-23). Data as JSON: /api/errors/6dfae729ccb6192c. Report an issue: GitHub.