laravel/framework · error · InvalidArgumentException

The binary codec format is required.

Error message

The binary codec format is required.

What it means

Thrown by AsBinary cast's castUsing() when the cast arguments array has no element at index 0. AsBinary is a parameterized cast that must be declared with a codec format (e.g. AsBinary::class.':uuid'); the format selects how the binary value is encoded/decoded via Illuminate\Support\BinaryCodec. Using the cast without a format is a declaration error, not a runtime data error.

Solutions

1. Specify the format when declaring the cast: 'column' => AsBinary::class.':uuid'.
2. Use ':ulid' if the column stores ULID-encoded binary values.
3. Provide the cast via the withCasts() method on a query: ->withCasts(['column' => AsBinary::class.':uuid']).
4. Confirm the allowed formats via Illuminate\Support\BinaryCodec::formats() (currently 'uuid', 'ulid', plus any registered custom codecs).

Example fix

// before
protected $casts = ['uuid' => AsBinary::class];

// after
protected $casts = ['uuid' => AsBinary::class.':uuid'];

if (! isset($arguments[0]) || ! in_array($arguments[0], \Illuminate\Support\BinaryCodec::formats(), true)) {
    throw new \InvalidArgumentException(
        'AsBinary cast requires a format: AsBinary::class.":uuid" or ":ulid"'
    );
}

function hasBinaryCastFormat(array $castArguments): bool {
    return isset($castArguments[0]);
}

When it happens

Trigger: Declaring a model cast as 'column' => AsBinary::class (no ':format' suffix) instead of AsBinary::class.':uuid'. The cast class is instantiated at model boot with an empty arguments array, and the constructor immediately throws.

Common situations: Copy-pasting from examples that omitted the format; upgrading to a version that added the required format argument to an existing AsBinary cast; misunderstanding that AsBinary is parameterized.

Related errors

• Unsupported binary codec format
• Property [ ] does not exist on the Eloquent builder…
• The --model and --except options cannot be combined.
• A driver must be specified.
• Cannot establish connection [$name] because another…

AI-assisted analysis of laravel/framework@e0f6eb3518 (2026-08-11). Data as JSON: /api/errors/86cd25fbc10b9565. Report an issue: GitHub.

Appendix: source

Thrown at src/Illuminate/Database/Eloquent/Casts/AsBinary.php:29

{
    /**
     * Get the caster class to use when casting from / to this cast target.
     *
     * @param  array{string}  $arguments
     * @return \Illuminate\Contracts\Database\Eloquent\CastsAttributes
     *
     * @throws \InvalidArgumentException
     */
    public static function castUsing(array $arguments)
    {
        return new class($arguments) implements CastsAttributes
        {
            protected string $format;

            public function __construct(protected array $arguments)
            {
                $this->format = $this->arguments[0]
                    ?? throw new InvalidArgumentException('The binary codec format is required.');

                if (! in_array($this->format, BinaryCodec::formats(), true)) {
                    throw new InvalidArgumentException(sprintf(
                        'Unsupported binary codec format [%s]. Allowed formats are: %s.',
                        $this->format,
                        implode(', ', BinaryCodec::formats()),
                    ));
                }
            }

            public function get($model, $key, $value, $attributes)
            {
                return BinaryCodec::decode($attributes[$key] ?? null, $this->format);
            }

            public function set($model, $key, $value, $attributes)
            {
                return [$key => BinaryCodec::encode($value, $this->format)];

View on GitHub (pinned to e0f6eb3518)