{"record":{"id":"84301da928902e85","repo":"Intervention/image","slug":"unable-to-find-encoder-for-unknown-file-extension","errorCode":null,"errorMessage":"Unable to find encoder for unknown file extension \"' . $extension . '\"","messagePattern":"Unable to find encoder for unknown file extension \"' \\. \\$extension \\. '\"","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"src/Encoders/FileExtensionEncoder.php","lineNumber":43,"sourceCode":"     * Create new encoder instance to encode to format of given file extension.\n     *\n     * @param null|string|FileExtension $extension Target file extension for example \"png\"\n     * @throws InvalidArgumentException\n     * @throws NotSupportedException\n     */\n    public function __construct(public null|string|FileExtension $extension = null, mixed ...$options)\n    {\n        if ($extension === '') {\n            throw new InvalidArgumentException('Unable to find file extension from empty string');\n        }\n\n        $mediaType = null;\n\n        if (is_string($extension)) {\n            try {\n                $mediaType = FileExtension::from(strtolower($extension))->mediaType();\n            } catch (Error) {\n                throw new NotSupportedException(\n                    'Unable to find encoder for unknown file extension \"' . $extension . '\"',\n                );\n            }\n        }\n\n        if ($extension instanceof FileExtension) {\n            $mediaType = $extension->mediaType();\n        }\n\n        parent::__construct($mediaType, ...$options);\n    }\n\n    /**\n     * {@inheritdoc}\n     *\n     * @see EncoderInterface::encode()\n     *\n     * @throws NotSupportedException","sourceCodeStart":25,"sourceCodeEnd":61,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Encoders/FileExtensionEncoder.php#L25-L61","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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"],"exampleFix":"// before\n$image->encodeUsingFileExtension('.jpg'); // dot makes it unknown\n\n// after\n$image->encodeUsingFileExtension(ltrim('.jpg', '.')); // 'jpg'\n// or statically safe:\nuse Intervention\\Image\\FileExtension;\n$image->encodeUsingFileExtension(FileExtension::JPG);","handlingStrategy":"type-guard","validationCode":"use Intervention\\Image\\FileExtension;\n\n$ext = strtolower(ltrim($extension, '.'));\nif (FileExtension::tryFrom($ext) === null) {\n    $ext = 'jpg'; // or reject the request\n}\n$image->encodeUsingFileExtension($ext);","typeGuard":"use Intervention\\Image\\FileExtension;\n\nfunction isSupportedExtension(string $extension): bool\n{\n    return FileExtension::tryFrom(strtolower(ltrim($extension, '.'))) !== null;\n}","tryCatchPattern":"use Intervention\\Image\\Exceptions\\NotSupportedException;\n\ntry {\n    $image->encodeUsingFileExtension($ext);\n} catch (NotSupportedException $e) {\n    // fall back to a known-good format\n    $image->encodeUsingFileExtension('png');\n}","preventionTips":["Normalize extensions: lowercase and strip any leading dot before passing","Whitelist user-supplied extensions against FileExtension::tryFrom()","Prefer passing FileExtension enum cases over strings"],"tags":["php","intervention-image","encoder","file-extension","not-supported"],"backgroundTag":"unsupported-file-format","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}