{"record":{"id":"e285b640a94ef3d6","repo":"symfony/http-foundation","slug":"parameter-s-cannot-be-converted-to-enum","errorCode":null,"errorMessage":"Parameter \"%s\" cannot be converted to enum: ","messagePattern":"Parameter \"(.+?)\" cannot be converted to enum: ","errorType":"exception","errorClass":"UnexpectedValueException","httpStatus":null,"severity":"error","filePath":"ParameterBag.php","lineNumber":202,"sourceCode":"     * @param class-string<T> $class\n     * @param ?T              $default\n     *\n     * @return ?T\n     *\n     * @psalm-return ($default is null ? T|null : T)\n     *\n     * @throws UnexpectedValueException if the parameter value cannot be converted to an enum\n     */\n    public function getEnum(string $key, string $class, ?\\BackedEnum $default = null): ?\\BackedEnum\n    {\n        if (null === $value = $this->get($key)) {\n            return $default;\n        }\n\n        try {\n            return $class::from($value);\n        } catch (\\ValueError|\\TypeError $e) {\n            throw new UnexpectedValueException(\\sprintf('Parameter \"%s\" cannot be converted to enum: ', $key).$e->getMessage().'.', $e->getCode(), $e);\n        }\n    }\n\n    /**\n     * Filter key.\n     *\n     * @param int                                              $filter  FILTER_* constant\n     * @param int|array{flags?: int, options?: array|\\Closure} $options Flags from FILTER_* constants, and a Closure when using FILTER_CALLBACK\n     *\n     * @see https://php.net/filter-var\n     *\n     * @throws UnexpectedValueException if the parameter value is a non-stringable object\n     * @throws UnexpectedValueException if the parameter value is invalid and \\FILTER_NULL_ON_FAILURE is not set\n     */\n    public function filter(string $key, mixed $default = null, int $filter = \\FILTER_DEFAULT, mixed $options = []): mixed\n    {\n        $value = $this->get($key, $default);\n","sourceCodeStart":184,"sourceCodeEnd":220,"githubUrl":"https://github.com/symfony/http-foundation/blob/5aea19cd678fa4140f6108406f1096de5e9ed6e4/ParameterBag.php#L184-L220","documentation":"ParameterBag::getEnum() casts a stored parameter to a backed enum via $class::from($value). When the value is not a valid backing value (ValueError) or of an incompatible type (TypeError), it wraps the failure in an UnexpectedValueException naming the parameter key, appending the original message and chaining the original exception.","triggerScenarios":"$bag->getEnum('mode', Mode::class) where the stored value is a string/int that no enum case backs (e.g. 'live' when only 'test'/'prod' exist), a wrong-typed value (array, object), or a null stored value with no default.","commonSituations":"Config file contains an enum string that was renamed or is not a backed case after adding new enum members; environment variable contains an unexpected token; PHP version/type drift making the value a non-scalar.","solutions":["Validate the stored value against $class::tryFrom($value) before calling getEnum and handle null","Update the config/env value to one of the enum's backed values","Catch UnexpectedValueException (previous is the ValueError/TypeError) and fall back to a default case","Add the missing case to the enum if the new value is legitimate"],"exampleFix":"// before\n$mode = $bag->getEnum('mode', Mode::class); // throws for 'staging'\n// after\n$mode = Mode::tryFrom((string) $bag->get('mode')) ?? Mode::Test;","handlingStrategy":"try-catch","validationCode":"$raw = $bag->get('mode');\nif (null !== $raw && null === Mode::tryFrom((string) $raw) && null === Mode::tryFrom((int) $raw)) {\n    throw new \\InvalidArgumentException(\"'mode' is not a backed value of \".Mode::class);\n}","typeGuard":"function isBackedBy(Mixed $v, string $enumClass): bool {\n    return is_subclass_of($enumClass, \\BackedEnum::class) && null !== $enumClass::tryFrom(is_int($v) || is_string($v) ? $v : (string) $v);\n}","tryCatchPattern":"try {\n    $mode = $bag->getEnum('mode', Mode::class);\n} catch (\\UnexpectedValueException $e) {\n    // $e->getPrevious() is the ValueError/TypeError\n    $mode = Mode::Test;\n}","preventionTips":["Prefer ::tryFrom() over ::from() when values come from user/config input","Keep enum backed values and config files in sync (rename values together)","Validate config against allowed values at application boot","Chain the previous exception for diagnostics when wrapping"],"tags":["parameters","enum","validation","configuration"],"backgroundTag":"invalid-enum-value","analyzedSha":"5aea19cd678fa4140f6108406f1096de5e9ed6e4","analyzedAt":"2026-09-13T01:52:22.855Z","contentChangedAt":"2026-09-13T01:52:22.855Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}