{"record":{"id":"7324e056e8a8f47f","repo":"Intervention/image","slug":"failed-to-encode-jp2-format","errorCode":null,"errorMessage":"Failed to encode jp2 format","messagePattern":"Failed to encode jp2 format","errorType":"exception","errorClass":"EncoderException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Imagick/Encoders/Jpeg2000Encoder.php","lineNumber":54,"sourceCode":"        }\n\n        try {\n            $imagick = clone $image->core()->native();\n            $imagick->setImageBackgroundColor('white');\n            $imagick->setBackgroundColor('white');\n            $imagick->setFormat($format);\n            $imagick->setImageFormat($format);\n            $imagick->setCompression($compression);\n            $imagick->setImageCompression($compression);\n            $imagick->setCompressionQuality($this->quality);\n            $imagick->setImageCompressionQuality($this->quality);\n\n            $result = new EncodedImage($imagick->getImagesBlob(), 'image/jp2');\n            $imagick->clear();\n\n            return $result;\n        } catch (ImagickException $e) {\n            throw new EncoderException('Failed to encode jp2 format', previous: $e);\n        }\n    }\n}\n","sourceCodeStart":36,"sourceCodeEnd":58,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Imagick/Encoders/Jpeg2000Encoder.php#L36-L58","documentation":"The Imagick driver's Jpeg2000Encoder flattens transparency onto a white background, sets format 'JP2' with JPEG compression and quality (src/Drivers/Imagick/Encoders/Jpeg2000Encoder.php:39-47), then serializes with getImagesBlob(). Any ImagickException is rethrown as EncoderException ('Failed to encode jp2 format') with the original as previous. JPEG 2000 output needs ImageMagick built with the OpenJPEG delegate, which many default builds exclude - the previous exception then says 'no encode delegate for this image format'.","triggerScenarios":"Calling toJpeg2000() or encoding to a *.jp2 target on the Imagick driver when setFormat('JP2')/setImageFormat('JP2') throws because the OpenJPEG coder is missing: php -r \"var_dump((new Imagick())->queryFormats('JP2'));\" returns an empty array. Also when quality-setting or blob serialization fails in partially capable builds.","commonSituations":"RHEL/CentOS and Alpine default ImageMagick packages without openjpeg; archival/scanning workflows migrating to JPEG 2000; environments where jp2 decode works but encode does not (asymmetric delegate sets).","solutions":["Read $e->getPrevious()->getMessage() to confirm the delegate error.","Check Imagick::queryFormats('JP2') on the failing host.","Install the OpenJPEG delegate (apt-get install libopenjp2-7-dev / dnf install openjpeg2-devel) and an ImageMagick build linked to it, then rebuild the imagick extension.","If JPEG 2000 is not a hard requirement, encode with toJpeg() or toWebp(), which are supported everywhere."],"exampleFix":"// before\n$encoded = $image->toJpeg2000(quality: 80);\n\n// after\n$jp2Supported = in_array('JP2', Imagick::queryFormats('JP2'), true);\n$encoded = $jp2Supported ? $image->toJpeg2000(quality: 80) : $image->toJpeg(quality: 80);","handlingStrategy":"validation","validationCode":"$jp2Supported = in_array('JP2', Imagick::queryFormats('JP2'), true);\nif (!$jp2Supported) {\n    throw new RuntimeException('JPEG 2000 encoding unavailable: ImageMagick lacks the OpenJPEG delegate');\n}\n$encoded = $image->toJpeg2000();","typeGuard":null,"tryCatchPattern":"try {\n    $encoded = $image->toJpeg2000(quality: 80);\n} catch (EncoderException $e) {\n    $reason = $e->getPrevious()?->getMessage() ?? $e->getMessage();\n    $encoded = $image->toJpeg(quality: 80); // degrade, then log $reason\n}","preventionTips":["Query JP2 support explicitly per environment before offering JPEG 2000 output.","Prefer universally supported formats unless an archival system mandates JP2.","Remember decode and encode delegate sets can differ - test the write path, not just the read path."],"tags":["jpeg2000","jp2","imagick","encode","delegate"],"backgroundTag":"imagick-no-encode-delegate","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}