{"record":{"id":"1aac573ee0ec2266","repo":"Intervention/image","slug":"unable-to-base64-decode-image-from-string","errorCode":null,"errorMessage":"Unable to Base64-decode image from string","messagePattern":"Unable to Base64-decode image from string","errorType":"exception","errorClass":"ImageDecoderException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Gd/Decoders/Base64ImageDecoder.php","lineNumber":37,"sourceCode":"     *\n     * @see DecoderInterface::supports()\n     */\n    public function supports(mixed $input): bool\n    {\n        return $this->couldBeBase64Data($input);\n    }\n\n    /**\n     * {@inheritdoc}\n     *\n     * @see DecoderInterface::decode()\n     */\n    public function decode(mixed $input): ImageInterface\n    {\n        try {\n            $data = $this->decodeBase64Data($input);\n        } catch (DecoderException) {\n            throw new ImageDecoderException('Unable to Base64-decode image from string');\n        }\n\n        try {\n            return parent::decode($data);\n        } catch (DecoderException) {\n            throw new ImageDecoderException('Base64-encoded data contains unsupported image type');\n        }\n    }\n}\n","sourceCodeStart":19,"sourceCodeEnd":47,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Gd/Decoders/Base64ImageDecoder.php#L19-L47","documentation":"Thrown by Base64ImageDecoder::decode when decodeBase64Data fails: base64_decode($input, true) returned false, or the decode/re-encode round trip did not match the input. In other words, the string routed to the base64 decoder is not canonical, strictly-valid Base64, so it is rejected with an ImageDecoderException before image decoding begins.","triggerScenarios":"Passing a string ending in '=' that is not well-formed Base64 (that suffix alone makes supports() claim it); strings containing a 'data:image/...;base64,' prefix, whitespace, or URL-safe '-'/'_' alphabet; base64 with stripped padding that fails the base64_encode round-trip check; binary data misrouted into Base64ImageDecoder::decode directly.","commonSituations":"Frontend sends a data URI where the backend expected bare base64; JSON payloads where newlines were inserted into long base64 strings; copy-paste artifacts (truncated strings, ellipsis); client libraries using base64url (JWT-style) encoding for image payloads.","solutions":["Sanitize the string: strip any 'data:...;base64,' prefix, remove whitespace/newlines, and re-pad with '=' to a multiple of 4","If the value is a full data URI, pass it as-is so DataUriImageDecoder handles it, or parse it with DataUri::parse() first","Validate before reading: base64_decode($s, true) !== false && base64_encode(base64_decode($s, true)) === preg_replace('/\\s+/', '', $s)","For base64url input, translate '-' => '+', '_' => '/' before handing it over"],"exampleFix":"// before\n$image = $manager->read($uploadedBase64); // contains \"data:image/png;base64,\" prefix\n// ImageDecoderException: Unable to Base64-decode image from string\n\n// after\n$b64 = preg_replace('#^data:[^;]+;base64,#', '', $uploadedBase64);\n$b64 = str_replace([\"\\n\", \"\\r\", ' '], '', $b64);\n$image = $manager->read($b64);","handlingStrategy":"validation","validationCode":"function normalizeBase64(string $input): string\n{\n    $b64 = preg_replace('#^data:[^;]+;base64,#', '', $input);\n    $b64 = str_replace([\"\\n\", \"\\r\", ' '], '', $b64);\n    return $b64 . str_repeat('=', (4 - strlen($b64) % 4) % 4);\n}\n\n$b64 = normalizeBase64($input);\n$decoded = base64_decode($b64, true);\nif ($decoded === false || base64_encode($decoded) !== $b64) {\n    throw new RuntimeException('Not valid canonical Base64');\n}","typeGuard":null,"tryCatchPattern":"try {\n    $image = $manager->read($b64);\n} catch (\\Intervention\\Image\\Exceptions\\ImageDecoderException $e) {\n    if (str_contains($e->getMessage(), 'Base64-decode')) {\n        // fix the encoding of the source value; retrying the same string will not help\n    }\n}","preventionTips":["Strip data-URI prefixes and all whitespace before passing base64 to read()","Translate base64url alphabets ('-'/'_') to standard Base64 on the server edge","Validate with base64_decode(strict) plus a re-encode round trip before storing"],"tags":["base64","decoder","input-sanitization","data-uri","gd-driver"],"backgroundTag":"invalid-base64","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}