{"record":{"id":"32d3ea9d51e6a0ab","repo":"cakephp/cakephp","slug":"unable-to-use-enum-s-for-type-s-must-be-a-backed-enum","errorCode":null,"errorMessage":"Unable to use enum `%s` for type `%s`, must be a backed enum.","messagePattern":"Unable to use enum `(.+?)` for type `(.+?)`, must be a backed enum\\.","errorType":"exception","errorClass":"DatabaseException","httpStatus":null,"severity":"error","filePath":"src/Database/Type/EnumType.php","lineNumber":76,"sourceCode":"        string $enumClassName,\n    ) {\n        parent::__construct($name);\n        $this->enumClassName = $enumClassName;\n\n        try {\n            $reflectionEnum = new ReflectionEnum($enumClassName);\n        } catch (ReflectionException $e) {\n            throw new DatabaseException(sprintf(\n                'Unable to use `%s` for type `%s`. %s.',\n                $enumClassName,\n                $name,\n                $e->getMessage(),\n            ));\n        }\n\n        $namedType = $reflectionEnum->getBackingType();\n        if ($namedType === null) {\n            throw new DatabaseException(\n                sprintf('Unable to use enum `%s` for type `%s`, must be a backed enum.', $enumClassName, $name),\n            );\n        }\n\n        $this->backingType = (string)$namedType;\n    }\n\n    /**\n     * Convert enum instances into the database format.\n     *\n     * @param mixed $value The value to convert.\n     * @param \\Cake\\Database\\Driver $driver The driver instance to convert with.\n     * @return string|int|null\n     * @throws \\InvalidArgumentException When the given value is not a valid value for the associated enum\n     */\n    public function toDatabase(mixed $value, Driver $driver): string|int|null\n    {\n        if ($value === null) {","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/cakephp/cakephp/blob/1128eba9b09f1946df684811350e26f2cef68fac/src/Database/Type/EnumType.php#L58-L94","documentation":"EnumType requires the associated PHP enum to be a backed enum (one declared with a string or int backing type, e.g. `enum Status: string`). This DatabaseException is thrown in the constructor when ReflectionEnum::getBackingType() returns null, i.e. the class is a valid enum but a pure/unit enum without backing values. Backed values are required to store the enum in a database column.","triggerScenarios":"Constructing EnumType with a unit enum such as `enum Status { case Active; case Inactive; }` (no `: string` / `: int` after the name).","commonSituations":"Migrating legacy unit enums to DB types; copying an enum defined for in-memory use only and wiring it to EnumType without adding a backing type; third-party enum classes that are not backed.","solutions":["Add a backing type to the enum: `enum Status: string { ... }` and give each case an explicit value, e.g. `case Active = 'active';`","If the enum cannot be changed, create a new backed enum for persistence and map to it in the entity","Use a non-EnumType (e.g. StringType) plus manual conversion if a unit enum must stay unit"],"exampleFix":"// before\nenum Status { case Active; case Inactive; }\n// after\nenum Status: string { case Active = 'active'; case Inactive = 'inactive'; }","handlingStrategy":"validation","validationCode":"if (enum_exists($class) && !(new \\ReflectionEnum($class))->getBackingType()) { throw new \\LogicException(\"{$class} must be a backed enum\"); }","typeGuard":"function isBackedEnumClass(string $class): bool { return enum_exists($class) && is_subclass_of($class, \\BackedEnum::class); }","tryCatchPattern":"try { $type = new EnumType('status', $class); } catch (\\Cake\\Database\\DatabaseException $e) { // fail fast at config time, not at save time }","preventionTips":["Always declare DB-backed enums as `enum X: string` or `enum X: int` with explicit case values","Check is_subclass_of($class, BackedEnum::class) when wiring types dynamically","Keep unit enums separate from persistence enums"],"tags":["php","cakephp","database","enum"],"backgroundTag":"invalid-enum-value","analyzedSha":"1128eba9b09f1946df684811350e26f2cef68fac","analyzedAt":"2026-09-12T12:07:00.388Z","contentChangedAt":"2026-09-12T12:07:00.388Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}