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

Pass an explicit Format: new FormatEncoder(Format::PNG) or $image->encodeUsingFormat(Format::PNG)

Intervention/image · error · NotSupportedException

Unable to find encoder by unknown origin image format

Error message

Unable to find encoder by unknown origin image format

What it means

FormatEncoder with format = null asks the image origin for its format via $image->origin()->format(). Origins that never recorded a format (blank images from ImageManager::create(), or binary input where no format was attached) make that call throw NotSupportedException, which encode() rethrows wrapped as 'Unable to find encoder by unknown origin image format' with the original as previous.

Source

Thrown at src/Encoders/FormatEncoder.php:42

     */
    public function __construct(protected ?Format $format = null, mixed ...$options)
    {
        $this->options = $options;
    }

    /**
     * {@inheritdoc}
     *
     * @see EncoderInterface::encode()
     *
     * @throws NotSupportedException
     */
    public function encode(ImageInterface $image): EncodedImageInterface
    {
        try {
            $format = is_null($this->format) ? $image->origin()->format() : $this->format;
        } catch (NotSupportedException $e) {
            throw new NotSupportedException('Unable to find encoder by unknown origin image format', previous: $e);
        }

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

View on GitHub (pinned to 5598b9e397)

Solutions

Pass an explicit Format: new FormatEncoder(Format::PNG) or $image->encodeUsingFormat(Format::PNG)
For blank/created images always decide the output format yourself - there is no source format to preserve
For binary input, prefer $image->encode() (AutoEncoder), which resolves via media type instead of origin format

Example fix

// before
use Intervention\Image\Encoders\FormatEncoder;
$image = $manager->create(1200, 630)->fill('#fff');
$image->encode(new FormatEncoder(null)); // origin has no format

// after
use Intervention\Image\Format;
$image->encodeUsingFormat(Format::PNG);

Defensive patterns

Strategy: validation

Validate before calling

try {
    $format = $image->origin()->format();
} catch (\Intervention\Image\Exceptions\NotSupportedException $e) {
    $format = \Intervention\Image\Format::PNG; // created/binary images have no origin format
}
$image->encodeUsingFormat($format);

Try / catch

use Intervention\Image\Exceptions\NotSupportedException;

try {
    $image->encode(new FormatEncoder(null));
} catch (NotSupportedException $e) {
    $image->encodeUsingFormat(\Intervention\Image\Format::PNG);
}

Prevention

For images from create() always specify the target format explicitly
Do not assume origin()->format() exists for binary-string input
Use encode() (AutoEncoder) when you want automatic format resolution

When it happens

Trigger: Applying new FormatEncoder(null) to an image created with ImageManager::create(600, 400), or to an image decoded from a raw binary string whose origin was never assigned a Format.

Common situations: Building composites or canvases and then encoding them without naming a target format; pipelines that encode generically ('keep the source format') but receive input whose format metadata is absent.

Related errors

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