Intervention/image · error · NotSupportedException

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

Error message

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

What it means

The runtime sibling of the constructor check: encoderByFileExtension() calls FileExtension::from(strtolower($extension)) and converts the enum's ValueError into this NotSupportedException when the value matches no FileExtension case. Unlike the constructor check, this one also fires for extensions that arrive indirectly, e.g. extracted from a save path by FilePathEncoder or returned by the image origin.

Source

Thrown at src/Encoders/FileExtensionEncoder.php:94

        );
    }

    /**
     * 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

Save under an extension the library supports: jpg, jpeg, pjpg, pjpeg, png, gif, webp, avif, bmp, tif, tiff, jp2, j2k, jp2k, jpf, jpm, jpg2, j2c, jpc, jpx, heic, heif, jxl, ico
If you must keep the original filename, encode explicitly by format: $image->encodeUsingFormat(Format::PNG)->save('output.svg') is also wrong - instead pick the encoder first and write the bytes yourself with file_put_contents()
Validate output filenames from users against FileExtension::tryFrom() before calling save()

Example fix

// before
$image->save('uploads/' . $userChosenName); // 'avatar.svg' -> unknown extension

// after
$ext = strtolower(pathinfo($userChosenName, PATHINFO_EXTENSION));
$safe = FileExtension::tryFrom($ext) ? $userChosenName : 'avatar.png';
$image->save('uploads/' . $safe);

Defensive patterns

Strategy: type-guard

Validate before calling

use Intervention\Image\FileExtension;

$pathExt = strtolower(pathinfo($path, PATHINFO_EXTENSION));
if (FileExtension::tryFrom($pathExt) === null) {
    throw new RuntimeException('Output format not supported: ' . $pathExt);
}
$image->save($path);

Type guard

use Intervention\Image\FileExtension;

function pathHasSupportedExtension(string $path): bool
{
    $ext = strtolower(pathinfo($path, PATHINFO_EXTENSION));

    return $ext !== '' && FileExtension::tryFrom($ext) !== null;
}

Try / catch

use Intervention\Image\Exceptions\NotSupportedException;

try {
    $image->save($path);
} catch (NotSupportedException $e) {
    // extension names a format the library cannot encode; pick explicitly
    file_put_contents($path, (string) $image->encodeUsingFormat(\Intervention\Image\Format::PNG));
}

Prevention

Constrain output filenames to a fixed set of supported extensions
Validate user-chosen filenames before passing them to save()
Remember Image::save() falls back to MediaTypeEncoder only for EncoderException, not for NotSupportedException

When it happens

Trigger: Calling $image->save('output.svg') or $image->encodeUsingPath('/tmp/out.tga') - FilePathEncoder extracts the extension from the path and hands it to encoderByFileExtension(), which cannot map it. Also fired when origin()->fileExtension() returns an unsupported non-empty value.

Common situations: Saving under a filename whose extension names a format the library cannot encode (svg, pdf, psd); writing thumbnails with exotic extensions; user-supplied output filenames trusted verbatim.

Related errors

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