doctrine/annotations · error · AnnotationException

The annotation @ declared on does not have a property named…

Error message

The annotation @%s declared on %s does not have a property named "%s"
that can be set through its named arguments constructor.
Available named arguments: %s

What it means

Doctrine Annotations throws this when an annotation class uses a PHP 8 named-argument constructor (has_named_argument_constructor) and the DocParser encounters an attribute key in the annotation usage that is not a named parameter of the annotation's constructor. The parser validates each key in $values against the constructor's parameter list before instantiating, so an unknown key aborts annotation creation. The message lists the valid named arguments to help you spot the typo.

Solutions

Fix the attribute name in the annotation usage to match one of the annotation class's constructor parameters (see 'Available named arguments' in the message).
Read the annotation class's constructor to confirm the exact parameter names and types.
If the annotation class is yours and the key is intentional, add the corresponding promoted constructor parameter.
Check the installed dependency version: the annotation class may differ from the version your docs assume; update usages or the dependency.

Example fix

// before
/** @Column(typ="string", nullable=true) */
// after
/** @Column(type="string", nullable=true) */

Defensive patterns

Strategy: validation

Validate before calling

$ctor = (new ReflectionClass(MyAnnotation::class))->getConstructor();
$allowed = $ctor ? array_map(fn($p) => $p->getName(), $ctor->getParameters()) : [];
$used = ['type' => 'string', 'nmae' => 'x']; // keys from the docblock
$unknown = array_diff(array_keys($used), $allowed);
if ($unknown) {
    throw new LogicException('Unknown annotation attributes: ' . implode(',', $unknown));
}

Type guard

function isValidAnnotationAttribute(string $class, string $attr): bool {
    $ctor = (new ReflectionClass($class))->getConstructor();
    if ($ctor === null) return false;
    foreach ($ctor->getParameters() as $p) {
        if ($p->getName() === $attr) return true;
    }
    return false;
}

Try / catch

try {
    $parsed = $reader->getPropertyAnnotation($prop, MyAnnotation::class);
} catch (AnnotationException $e) {
    if (str_contains($e->getMessage(), 'does not have a property named')) {
        // fall back to defaults or re-raise with file/line context
    }
    throw $e;
}

Prevention

Keep docblock attributes in sync with the annotation class constructor after refactors.
Run annotation parsing in CI on all files to catch typos early.
Enable IDE annotation support (e.g. PhpStorm Doctrine plugin) for attribute autocomplete.
Pin annotation library versions and re-check usages when upgrading.

When it happens

Trigger: Using an annotation like @Column(type="string", nonexistent="x") where the annotation class has a promoted-properties constructor and 'nonexistent' is not one of its constructor parameter names. Also triggered after upgrading an annotation class whose constructor signature changed (renamed/removed parameters) while call sites still use the old keys.

Common situations: Typos in annotation attribute names; migrating annotations to PHP 8 constructor promotion without updating usages; IDE autocomplete on a different annotation version than the one installed; copying annotation usage from documentation of a different library version.

Related errors

AI-assisted analysis of doctrine/annotations@17815fb6b2 (2026-09-15). Data as JSON: /api/errors/2cc32e200c95c960. Report an issue: GitHub.

Appendix: source

Thrown at lib/Doctrine/Common/Annotations/DocParser.php:941

                        }
                    }
                }
            } elseif (gettype($values[$property]) !== $type['type'] && ! $values[$property] instanceof $type['type']) {
                throw AnnotationException::attributeTypeError(
                    $property,
                    $originalName,
                    $this->context,
                    'a(n) ' . $type['value'],
                    $values[$property]
                );
            }
        }

        if (self::$annotationMetadata[$name]['has_named_argument_constructor']) {
            if (PHP_VERSION_ID >= 80000) {
                foreach ($values as $property => $value) {
                    if (! isset(self::$annotationMetadata[$name]['constructor_args'][$property])) {
                        throw AnnotationException::creationError(sprintf(
                            <<<'EXCEPTION'
The annotation @%s declared on %s does not have a property named "%s"
that can be set through its named arguments constructor.
Available named arguments: %s
EXCEPTION
                            ,
                            $originalName,
                            $this->context,
                            $property,
                            implode(', ', array_keys(self::$annotationMetadata[$name]['constructor_args']))
                        ));
                    }
                }

                return $this->instantiateAnnotiation($originalName, $this->context, $name, $values);
            }

            $positionalValues = [];

View on GitHub (pinned to 17815fb6b2)