Intervention/image · error · InvalidArgumentException

Image source must be binary data of type string or instance…

Error message

Image source must be binary data of type string or instance of Stringable

What it means

Contract violation of BinaryImageDecoder::decode: the input is neither a PHP string nor a Stringable object, so it cannot be raw image binary. This InvalidArgumentException is a programmer-error guard — normal manager routing (supports() via couldBeBinaryData) already filters non-strings, so hitting it means the decoder was called directly or with an unexpected value type.

Solutions

Cast or stringify the value before calling: (string) $value, or fetch stream contents with (string) $stream
Add a type guard: is_string($input) || $input instanceof Stringable before invoking decode
Make the calling code's signature honest (string $input instead of mixed) so PHP itself rejects bad types earlier
If you meant to read a file path, stream, or GdImage, route through ImageManager::read() instead of the binary decoder directly

Example fix

// before
$decoder = new BinaryImageDecoder();
$image = $decoder->decode($request->file('avatar')); // UploadedFile object
// InvalidArgumentException: Image source must be binary data ...

// after
$image = $manager->read($request->file('avatar')->getContent());
// or let the manager auto-route: $manager->read($request->file('avatar')->getRealPath())

Defensive patterns

Strategy: type-guard

Validate before calling

if (!is_string($input) && !$input instanceof \Stringable) {
    throw new InvalidArgumentException('Expected binary string, got ' . get_debug_type($input));
}

Type guard

/**
 * @param mixed $input
 */
function isBinaryLike(mixed $input): bool
{
    return is_string($input) || $input instanceof \Stringable;
}

Try / catch

try {
    $image = $decoder->decode($input);
} catch (\Intervention\Image\Exceptions\InvalidArgumentException $e) {
    // programmer error: fix the call site, do not catch-and-continue in production
    throw $e;
}

Prevention

Prefer ImageManager::read() over direct decoder calls so routing is automatic
Type your variables as string/Stringable upstream instead of mixed
TurnUploadedFile/stream inputs into strings with getContent()/(string) $stream first

When it happens

Trigger: Calling BinaryImageDecoder (or a subclass like Base64ImageDecoder) ->decode() directly with null, an int, an array, a PSR-7 stream, or an SplFileObject; passing a resource from file_get_contents(..., use include path) style calls that can return false/null; untyped mixed values flowing from decoded JSON into decoder calls.

Common situations: Custom decoder chains wired manually into a factory; refactorings that changed an upstream return type from string to object/null; optional fields (nullable string) passed without a null check; unit tests exercising the decoder with scalar literals.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

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

    {
        return $this->couldBeBinaryData($input);
    }

    /**
     * {@inheritdoc}
     *
     * @see DecoderInterface::decode()
     *
     * @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

View on GitHub (pinned to 5598b9e397)