{"id":"86cd25fbc10b9565","repo":"laravel/framework","slug":"the-binary-codec-format-is-required","errorCode":null,"errorMessage":"The binary codec format is required.","messagePattern":"The binary codec format is required\\.","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/Illuminate/Database/Eloquent/Casts/AsBinary.php","lineNumber":29,"sourceCode":"{\n    /**\n     * Get the caster class to use when casting from / to this cast target.\n     *\n     * @param  array{string}  $arguments\n     * @return \\Illuminate\\Contracts\\Database\\Eloquent\\CastsAttributes\n     *\n     * @throws \\InvalidArgumentException\n     */\n    public static function castUsing(array $arguments)\n    {\n        return new class($arguments) implements CastsAttributes\n        {\n            protected string $format;\n\n            public function __construct(protected array $arguments)\n            {\n                $this->format = $this->arguments[0]\n                    ?? throw new InvalidArgumentException('The binary codec format is required.');\n\n                if (! in_array($this->format, BinaryCodec::formats(), true)) {\n                    throw new InvalidArgumentException(sprintf(\n                        'Unsupported binary codec format [%s]. Allowed formats are: %s.',\n                        $this->format,\n                        implode(', ', BinaryCodec::formats()),\n                    ));\n                }\n            }\n\n            public function get($model, $key, $value, $attributes)\n            {\n                return BinaryCodec::decode($attributes[$key] ?? null, $this->format);\n            }\n\n            public function set($model, $key, $value, $attributes)\n            {\n                return [$key => BinaryCodec::encode($value, $this->format)];","sourceCodeStart":11,"sourceCodeEnd":47,"githubUrl":"https://github.com/laravel/framework/blob/bd6b5437e6ad87bb49f9b426724f07a9f64e9683/src/Illuminate/Database/Eloquent/Casts/AsBinary.php#L11-L47","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use the provided helper to attach a format: AsBinary::uuid() or AsBinary::ulid(), which yield 'AsBinary:uuid' / 'AsBinary:ulid'.","Or specify the format inline in the cast string: protected $casts = ['uuid' => 'binary:uuid'];.","For custom formats, use AsBinary::of($format) after registering the format with BinaryCodec.","Verify the cast resolves to a string containing ':'."],"exampleFix":"// before\nprotected $casts = ['uuid' => AsBinary::class];\n\n// after\nprotected $casts = ['uuid' => AsBinary::uuid()];\n// or\nprotected $casts = ['uuid' => 'binary:uuid'];","handlingStrategy":"validation","validationCode":"foreach ((new \\ReflectionClass($model))->getDefaultProperties()['casts'] ?? [] as $col => $cast) {\n    if ($cast === \\Illuminate\\Database\\Eloquent\\Casts\\AsBinary::class) {\n        throw new \\RuntimeException(\"Cast for [$col] must specify a binary format, e.g. AsBinary::uuid().\");\n    }\n}","typeGuard":"function binaryCastHasFormat(string $cast): bool {\n    return ! ($cast === \\Illuminate\\Database\\Eloquent\\Casts\\AsBinary::class\n        || str_ends_with($cast, ':'.\\Illuminate\\Database\\Eloquent\\Casts\\AsBinary::class));\n}","tryCatchPattern":null,"preventionTips":["Always use AsBinary::uuid()/AsBinary::ulid()/AsBinary::of($f) rather than the bare class.","Use the 'binary:<format>' cast string consistently.","Add a test that hydrates each model with a binary cast.","Document required formats in the model's docblocks."],"tags":["eloquent","casts","binary","configuration"],"analyzedSha":"bd6b5437e6ad87bb49f9b426724f07a9f64e9683","analyzedAt":"2026-08-06T00:28:32.783Z","schemaVersion":2}