laravel/framework · error · InvalidArgumentException

The binary codec format is required.

Error message

The binary codec format is required.

What it means

Thrown by AsBinary::castUsing()'s anonymous caster when the cast was registered without a format argument (e.g. 'binary' instead of 'binary:uuid'). The AsBinary castable requires a codec format (uuid, ulid, or a custom registered format) to know how to encode/decode the binary column.

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 bd6b5437e6)

Solutions

1. Use the provided helper to attach a format: AsBinary::uuid() or AsBinary::ulid(), which yield 'AsBinary:uuid' / 'AsBinary:ulid'.
2. Or specify the format inline in the cast string: protected $casts = ['uuid' => 'binary:uuid'];.
3. For custom formats, use AsBinary::of($format) after registering the format with BinaryCodec.
4. Verify the cast resolves to a string containing ':'.

Example fix

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

// after
protected $casts = ['uuid' => AsBinary::uuid()];
// or
protected $casts = ['uuid' => 'binary:uuid'];

foreach ((new \ReflectionClass($model))->getDefaultProperties()['casts'] ?? [] as $col => $cast) {
    if ($cast === \Illuminate\Database\Eloquent\Casts\AsBinary::class) {
        throw new \RuntimeException("Cast for [$col] must specify a binary format, e.g. AsBinary::uuid().");
    }
}

function binaryCastHasFormat(string $cast): bool {
    return ! ($cast === \Illuminate\Database\Eloquent\Casts\AsBinary::class
        || str_ends_with($cast, ':'.\Illuminate\Database\Eloquent\Casts\AsBinary::class));
}

When it happens

Trigger: Declaring a cast like protected $casts = ['uuid' => AsBinary::class]; (no format) or ->castUsing([]). The caster constructor reads $arguments[0] and throws when it's unset.

Common situations: Following an older tutorial that used the plain 'binary' cast; migrating from a custom binary cast to AsBinary without supplying the format; typo in the cast string.

Related errors

• Unsupported binary codec format [%s]. Allowed formats are: %
• Model attribute value is an object but does not have a __toS
• Callback must be a callable, callback array, or a 'Class@met
• Auth guard [{$name}] is not defined.
• Auth driver [{$config['driver']}] for guard [{$name}] is not

AI-assisted analysis of laravel/framework@bd6b5437e6 (2026-08-06). Data as JSON: /data/errors/86cd25fbc10b9565.json. Report an issue: GitHub.