Intervention/image · error · NotSupportedException

Unable to find encoder for unknown file extension "' . $exte

Error message

Unable to find encoder for unknown file extension "' . $extension . '"

What it means

FileExtensionEncoder maps the extension you pass to a case of the FileExtension enum via FileExtension::from(strtolower($extension)). Supported values are jpg, jpeg, pjpg, pjpeg, png, gif, webp, avif, bmp, tif, tiff, jp2, j2k, jp2k, jpf, jpm, jpg2, j2c, jpc, jpx, heic, heif, jxl and ico. When no case matches, the enum throws a ValueError which the constructor converts into this NotSupportedException, so encoding fails fast at encoder construction instead of at encode time.

Source

Thrown at src/Encoders/FileExtensionEncoder.php:43

     * 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();
        }

        parent::__construct($mediaType, ...$options);
    }

    /**
     * {@inheritdoc}
     *
     * @see EncoderInterface::encode()
     *
     * @throws NotSupportedException

View on GitHub (pinned to 5598b9e397)

Solutions

Remove any leading dot from the extension before passing it: pass 'jpg', not '.jpg'
Use one of the supported extensions: jpg, jpeg, pjpg, pjpeg, png, gif, webp, avif, bmp, tif, tiff, jp2, j2k, jp2k, jpf, jpm, jpg2, j2c, jpc, jpx, heic, heif, jxl, ico
Pass a FileExtension enum case (e.g. FileExtension::PNG) instead of a string so validity is checked statically
If the extension comes from user input, validate it with FileExtension::tryFrom(strtolower($ext)) and fall back to a safe default format

Example fix

// before
$image->encodeUsingFileExtension('.jpg'); // dot makes it unknown

// after
$image->encodeUsingFileExtension(ltrim('.jpg', '.')); // 'jpg'
// or statically safe:
use Intervention\Image\FileExtension;
$image->encodeUsingFileExtension(FileExtension::JPG);

Defensive patterns

Strategy: type-guard

Validate before calling

use Intervention\Image\FileExtension;

$ext = strtolower(ltrim($extension, '.'));
if (FileExtension::tryFrom($ext) === null) {
    $ext = 'jpg'; // or reject the request
}
$image->encodeUsingFileExtension($ext);

Type guard

use Intervention\Image\FileExtension;

function isSupportedExtension(string $extension): bool
{
    return FileExtension::tryFrom(strtolower(ltrim($extension, '.'))) !== null;
}

Try / catch

use Intervention\Image\Exceptions\NotSupportedException;

try {
    $image->encodeUsingFileExtension($ext);
} catch (NotSupportedException $e) {
    // fall back to a known-good format
    $image->encodeUsingFileExtension('png');
}

Prevention

Normalize extensions: lowercase and strip any leading dot before passing
Whitelist user-supplied extensions against FileExtension::tryFrom()
Prefer passing FileExtension enum cases over strings

When it happens

Trigger: Constructing new FileExtensionEncoder('svg'), calling $image->encodeUsingFileExtension('tga'), or passing an extension with a leading dot such as '.jpg' (the dot is never stripped, so it matches no enum case and strtolower cannot save it).

Common situations: Passing '.png' instead of 'png'; trying to encode formats the library cannot write (svg, pdf, psd, tga); forwarding user-supplied filenames or extensions to the encoder without whitelisting; code migrated from Intervention Image v2 where format handling differed.

Related errors

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