laravel/framework · error · InvalidArgumentException

Unsupported binary codec format

Error message

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

What it means

Thrown by AsBinary cast's constructor when the supplied format is not in BinaryCodec::formats(). The default allowed formats are 'uuid' and 'ulid' (plus any custom codecs registered with BinaryCodec). Any other string (typos like 'guid', 'binary', 'uuidv4') is rejected at model boot with the allowed list included in the message.

Solutions

Use one of the built-in formats: 'uuid' or 'ulid'.
If you need a custom encoding, register it first via Illuminate\Support\BinaryCodec (add a custom codec) so BinaryCodec::formats() includes your name, then declare AsBinary::class.':<yourformat>'.
Fix typos in the cast string (the format is everything after the colon).
Inspect the exact allowed list at runtime: \Illuminate\Support\BinaryCodec::formats().

Example fix

// before
protected $casts = ['id' => AsBinary::class.':guid'];

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

Defensive patterns

Strategy: validation

Validate before calling

if (! in_array($format, \Illuminate\Support\BinaryCodec::formats(), true)) {
    throw new \InvalidArgumentException(
        'Format must be one of: '.implode(', ', \Illuminate\Support\BinaryCodec::formats())
    );
}

Type guard

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

Prevention

Use only 'uuid' or 'ulid' for the AsBinary cast unless you registered a custom codec.
Register custom codecs via Illuminate\Support\BinaryCodec before referencing them in casts.
Assert allowed formats at boot with a test that checks model casts against BinaryCodec::formats().

When it happens

Trigger: Declaring 'column' => AsBinary::class.':guid' or any format string other than uuid/ulid; using a format name that was meant to be registered as a custom codec but wasn't; typo in the cast declaration.

Common situations: Guessing a format name; renaming from a previous version's format; forgetting to register a custom codec before using it in a cast.

Related errors

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

Appendix: 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 e0f6eb3518)