symfony/routing · error · InvalidArgumentException

Case must be a "BackedEnum" instance

Error message

Case must be a "BackedEnum" instance, "%s" given.

What it means

EnumRequirement accepts either a single enum class-string or an array of enum cases. When an array is passed, every element must be a BackedEnum instance; this error is thrown for any non-backed enum (unit enum) or non-enum value found in the array.

Solutions

1. Back the enum with string or int values (e.g. enum Status: string { case Active = 'active'; }) and pass backed cases or the class-string
2. Pass a single backed enum class-string instead of an array of cases
3. Filter the array to contain only BackedEnum instances before constructing the requirement

Example fix

// before
enum Status { case Active; case Inactive; }
$req = new EnumRequirement([Status::Active, Status::Inactive]);
// after
enum Status: string { case Active = 'active'; case Inactive = 'inactive'; }
$req = new EnumRequirement(Status::class);

$cases = (array) $input;
foreach ($cases as $c) {
    if (!$c instanceof \BackedEnum) throw new \InvalidArgumentException('All cases must be BackedEnum instances');
}

function isBackedEnumCaseList(array $cases): bool {
    return array_all($cases, fn($c) => $c instanceof \BackedEnum);
}

try {
    $requirement = new EnumRequirement($input);
} catch (\InvalidArgumentException $e) {
    // log and skip/fix the enum configuration
}

When it happens

Trigger: new EnumRequirement(SomeUnitEnum::class) where SomeUnitEnum is a plain (non-backed) enum, or passing an array mixing BackedEnum cases with unit enum cases, plain strings, or other values.

Common situations: Developers convert a unit enum to a route requirement (requirements only work with backed enums since they must map to string/int URL values), or accidentally pass enum class-strings mixed with case instances in the array.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• " :: " is not a case of " ".
• " " is not a "BackedEnum" class.
• Route alias " " can not reference itself.
• The router " " cannot be warmed up because it does not…
• Cannot unserialize Symfony\Component\Routing\CompiledRoute

AI-assisted analysis of symfony/routing@83fa223250 (2026-09-14). Data as JSON: /api/errors/5d8026355ec3b3eb. Report an issue: GitHub.

Appendix: source

Thrown at Requirement/EnumRequirement.php:38

    /**
     * @template T of \BackedEnum
     *
     * @param class-string<T>|list<T> $cases
     */
    public function __construct(string|array $cases = [])
    {
        if (\is_string($cases)) {
            if (!is_subclass_of($cases, \BackedEnum::class, true)) {
                throw new InvalidArgumentException(\sprintf('"%s" is not a "BackedEnum" class.', $cases));
            }

            $cases = $cases::cases();
        } else {
            $class = null;

            foreach ($cases as $case) {
                if (!$case instanceof \BackedEnum) {
                    throw new InvalidArgumentException(\sprintf('Case must be a "BackedEnum" instance, "%s" given.', get_debug_type($case)));
                }

                $class ??= $case::class;

                if (!$case instanceof $class) {
                    throw new InvalidArgumentException(\sprintf('"%s::%s" is not a case of "%s".', get_debug_type($case), $case->name, $class));
                }
            }
        }

        $this->requirement = implode('|', array_map(static fn ($e) => preg_quote($e->value), $cases));
    }

    public function __toString(): string
    {
        return $this->requirement;
    }
}

View on GitHub (pinned to 83fa223250)