{"record":{"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/e0f6eb3518ac29fbbca8529e97d0df7fc9f24481/src/Illuminate/Database/Eloquent/Casts/AsBinary.php#L11-L47","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Specify the format when declaring the cast: 'column' => AsBinary::class.':uuid'.","Use ':ulid' if the column stores ULID-encoded binary values.","Provide the cast via the withCasts() method on a query: ->withCasts(['column' => AsBinary::class.':uuid']).","Confirm the allowed formats via Illuminate\\Support\\BinaryCodec::formats() (currently 'uuid', 'ulid', plus any registered custom codecs)."],"exampleFix":"// before\nprotected $casts = ['uuid' => AsBinary::class];\n\n// after\nprotected $casts = ['uuid' => AsBinary::class.':uuid'];","handlingStrategy":"validation","validationCode":"if (! isset($arguments[0]) || ! in_array($arguments[0], \\Illuminate\\Support\\BinaryCodec::formats(), true)) {\n    throw new \\InvalidArgumentException(\n        'AsBinary cast requires a format: AsBinary::class.\":uuid\" or \":ulid\"'\n    );\n}","typeGuard":"function hasBinaryCastFormat(array $castArguments): bool {\n    return isset($castArguments[0]);\n}","tryCatchPattern":null,"preventionTips":["Always declare AsBinary with a format suffix (e.g. AsBinary::class.':uuid').","Add a static test that boots each model and asserts AsBinary casts include a format.","Document the required format in the model's docblock."],"tags":["database","eloquent","casts","uuid","laravel"],"backgroundTag":null,"analyzedSha":"e0f6eb3518ac29fbbca8529e97d0df7fc9f24481","analyzedAt":"2026-08-11T20:52:37.562Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}