Intervention/image · error · InvalidArgumentException

Unable to decode binary data from empty string

Error message

Unable to decode binary data from empty string

What it means

BinaryImageDecoder::decode received a valid string-typed input, but after casting it is the empty string ''. There is nothing to decode, so an InvalidArgumentException is raised immediately — before any format sniffing. Like the sibling type check, this is an input-contract error, not a corrupt-file error.

Source

Thrown at src/Drivers/Gd/Decoders/BinaryImageDecoder.php:55

     *
     * @throws InvalidArgumentException
     * @throws ImageDecoderException
     * @throws DriverException
     * @throws StateException
     * @throws NotSupportedException
     */
    public function decode(mixed $input): ImageInterface
    {
        if (!is_string($input) && !$input instanceof Stringable) {
            throw new InvalidArgumentException(
                'Image source must be binary data of type string or instance of ' . Stringable::class,
            );
        }

        $input = (string) $input;

        if ($input === '') {
            throw new InvalidArgumentException('Unable to decode binary data from empty string');
        }

        return $this->isGifFormat($input) ? $this->decodeGif($input) : $this->decodeBinary($input);
    }

    /**
     * Decode image from given binary data
     *
     * @throws InvalidArgumentException
     * @throws ImageDecoderException
     * @throws DriverException
     * @throws StateException
     * @throws NotSupportedException
     */
    private function decodeBinary(string $input): ImageInterface
    {
        $gd = @imagecreatefromstring($input);

View on GitHub (pinned to 5598b9e397)

Solutions

1. Check for empty input at the boundary: if ($value === '' || $value === null) reject with a user-facing validation error
2. For uploads, verify size: $request->file('avatar')->getSize() > 0 or isValid()
3. Fix the producer of the empty string (the failed fetch/ob_get_clean) rather than special-casing the decoder call
4. Make fields required in form/request validation so empty payloads never reach image processing

Example fix

// before
$image = $manager->read($request->input('avatar_base64') ?? '');
// InvalidArgumentException: Unable to decode binary data from empty string

// after
$data = (string) $request->input('avatar_base64', '');
if ($data === '') {
    return back()->withErrors(['avatar_base64' => 'Avatar upload is required.']);
}
$image = $manager->read($data);

$data = (string) $input;
if ($data === '') {
    throw new InvalidArgumentException('Image data must not be empty');
}

function isNonEmptyBinary(mixed $input): bool
{
    return (is_string($input) || $input instanceof \Stringable) && (string) $input !== '';
}

When it happens

Trigger: Calling decode(''), passing a Stringable object whose __toString() returns '' (e.g. an empty value object), optional request parameters that defaulted to '', or variables from functions that returned an empty string on failure (e.g. a failed ob_get_clean or a remote fetch that returned an empty body).

Common situations: Empty file uploads (user submitted the form without choosing a file); upstream service returning 200 with an empty body; nullable fields cast to string; test harnesses iterating over fixtures where one fixture file is missing and file_get_contents warning was suppressed.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Image source must be binary data of type string or instance
• Failed to read media (MIME) type from binary data
• Image source must be data uri scheme of type string or Inter
• Image source must be of type Intervention\Image\EncodedImage
• Image source must be of type GdImage

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