What causes "Argument $extension must not be an empty string" in Intervention/image?

Ensure the extension passed or resolved from the origin is a non-empty, supported value

Intervention/image · error · InvalidArgumentException

Argument $extension must not be an empty string

Error message

Argument $extension must not be an empty string

What it means

encoderByFileExtension() is the shared helper that maps an extension to a concrete encoder; it rejects an empty string immediately with InvalidArgumentException before attempting any enum lookup. In normal usage it is reached when the extension resolved at encode time - typically $image->origin()->fileExtension() - is an empty string rather than null, for example a source path with a trailing dot like 'photo.' whose pathinfo extension is ''.

Source

Thrown at src/Encoders/FileExtensionEncoder.php:88

        }

        return $image->encode(
            $this->encoderByFileExtension(
                $extension,
            ),
        );
    }

    /**
     * Create matching encoder for given file extension
     *
     * @throws InvalidArgumentException
     * @throws NotSupportedException
     */
    protected function encoderByFileExtension(string|FileExtension $extension): EncoderInterface
    {
        if ($extension === '') {
            throw new InvalidArgumentException('Argument $extension must not be an empty string');
        }

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

        return $extension->format()->encoder(...$this->options);
    }
}

View on GitHub (pinned to 5598b9e397)

Solutions

Ensure the extension passed or resolved from the origin is a non-empty, supported value
Pass an explicit extension to the encoder instead of relying on origin metadata
If you subclass FileExtensionEncoder, guard the value before calling encoderByFileExtension()

Example fix

// before
$ext = $image->origin()->fileExtension(); // '' for source 'photo.'
$image->encode(new FileExtensionEncoder($ext));

// after
$ext = $image->origin()->fileExtension();
$image->encode(new FileExtensionEncoder($ext ?: 'png'));

Defensive patterns

Strategy: validation

Validate before calling

$ext = $image->origin()->fileExtension();
if (!is_string($ext) || $ext === '') {
    $ext = 'jpg';
}
$image->encode(new FileExtensionEncoder($ext));

Try / catch

use Intervention\Image\Exceptions\InvalidArgumentException;

try {
    $image->encode(new FileExtensionEncoder($ext));
} catch (InvalidArgumentException $e) {
    $image->encode(new FileExtensionEncoder('png'));
}

Prevention

Treat null and '' identically when reading origin()->fileExtension()
Reject or sanitize source filenames that end in a dot
In subclasses, never pass a computed extension to encoderByFileExtension() unchecked

When it happens

Trigger: Encoding an image whose origin file extension resolved to '' (source filename ending in a dot, or sanitization code that stripped the extension down to an empty string), or a custom encoder subclass calling encoderByFileExtension('') directly.

Common situations: Oddly named source files such as 'banner.' or 'image..'; filename sanitizers that strip characters and leave no extension; subclassed encoders that pass computed extension values without checking them.

Related errors

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