laravel/framework · error · InvalidArgumentException

Unsupported binary codec format [%s]. Allowed formats are: %

Error message

Unsupported binary codec format [%s]. Allowed formats are: %s.

What it means

Thrown by AsBinary::castUsing()'s caster when the supplied format string is not one returned by BinaryCodec::formats(). The whitelist (e.g. 'uuid', 'ulid', plus any user-registered formats) keeps binary encoding deterministic; an unknown format is rejected.

Source

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

     *
     * @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

Use one of the formats listed in the error message (typically 'uuid' or 'ulid').
Register your custom format with BinaryCodec before loading models: BinaryCodec::registerFormat('guid', $encoder, $decoder).
Inspect allowed formats at runtime: Illuminate\Support\BinaryCodec::formats().
Correct the typo / casing in the cast string.

Example fix

// before
protected $casts = ['id' => 'binary:guid'];

// after
protected $casts = ['id' => AsBinary::uuid()];
// or register first:
\Illuminate\Support\BinaryCodec::registerFormat('guid', $enc, $dec);
protected $casts = ['id' => 'binary:guid'];

Defensive patterns

Strategy: validation

Validate before calling

$format = substr($cast, strpos($cast, ':') + 1);
if (! in_array($format, \Illuminate\Support\BinaryCodec::formats(), true)) {
    throw new \RuntimeException("Unsupported binary format [$format].");
}

Type guard

function isSupportedBinaryFormat(string $format): bool {
    return in_array($format, \Illuminate\Support\BinaryCodec::formats(), true);
}

Prevention

Register custom formats with BinaryCodec before model hydration.
Inspect \Illuminate\Support\BinaryCodec::formats() when unsure of valid values.
Pin the framework version so format names don't change under you.
Add a boot-time config check for binary cast strings.

When it happens

Trigger: Declaring a cast like 'binary:guid', 'binary:base64', or any string not in BinaryCodec::formats(). The caster's in_array check fails and the sprintf message lists the allowed set.

Common situations: Guessing a format name; pre-registering a custom format on a different BinaryCodec instance; version mismatch where a format was renamed; typo in the cast string.

Related errors

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