What causes "Unable to find encoder by unknown origin file extension" in Intervention/image?

Pass an explicit extension: $image->encodeUsingFileExtension('png')

Intervention/image · error · NotSupportedException

Unable to find encoder by unknown origin file extension

Error message

Unable to find encoder by unknown origin file extension

What it means

When FileExtensionEncoder is constructed with extension = null, encode() falls back to the extension recorded in the image's Origin: $image->origin()->fileExtension(). Origins built from binary strings, base64 data, or blank images created with ImageManager::create() carry no file extension, so the fallback returns null and encode() throws this NotSupportedException.

Source

Thrown at src/Encoders/FileExtensionEncoder.php:69

        }

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

    /**
     * {@inheritdoc}
     *
     * @see EncoderInterface::encode()
     *
     * @throws NotSupportedException
     * @throws InvalidArgumentException
     */
    public function encode(ImageInterface $image): EncodedImageInterface
    {
        $extension = is_null($this->extension) ? $image->origin()->fileExtension() : $this->extension;

        if ($extension === null) {
            throw new NotSupportedException('Unable to find encoder by unknown origin file extension');
        }

        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 === '') {

View on GitHub (pinned to 5598b9e397)

Solutions

Pass an explicit extension: $image->encodeUsingFileExtension('png')
Read the image from a file path or SplFileInfo instead of a binary string so the origin records the extension
If the input really is binary, prefer the format-based API: $image->encodeUsingFormat(Format::JPEG) or plain $image->encode() which works from the media type

Example fix

// before
$image = $manager->read($request->file('photo')->getContent());
$image->encodeUsingFileExtension(); // origin has no extension

// after
$image->encodeUsingFileExtension('webp');

Defensive patterns

Strategy: validation

Validate before calling

$ext = $image->origin()->fileExtension();
if ($ext === null || $ext === '') {
    $ext = 'png'; // binary origins carry no extension
}
$image->encodeUsingFileExtension($ext);

Try / catch

use Intervention\Image\Exceptions\NotSupportedException;

try {
    $image->encodeUsingFileExtension();
} catch (NotSupportedException $e) {
    $image->encodeUsingFileExtension('png');
}

Prevention

When input is a binary string, always name the target extension explicitly
Prefer reading from file paths or SplFileInfo so the origin records metadata
For 'keep the source format' behavior on binary input use encode(), which resolves by media type

When it happens

Trigger: Calling $image->encodeUsingFileExtension() (or applying new FileExtensionEncoder(null)) on an image that was read from a binary string, e.g. ImageManager::read(file_get_contents('photo.jpg')), or on an image from ImageManager::create(100, 100), because neither origin records a file extension.

Common situations: Processing HTTP uploads via UploadedFile->getContent(), fetching remote images with Guzzle/HTTP clients into strings, storing images as database blobs, or generating new canvases - in all these cases the origin has no file path and therefore no file extension.

Related errors

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