doctrine/annotations · error · AnnotationException

An error occurred while instantiating the annotation @

Error message

An error occurred while instantiating the annotation @%s declared on %s: "%s".

What it means

DocParser wraps any Throwable thrown by the annotation class's constructor in this generic creation error via instantiateAnnotiation(). The annotation itself failed to construct (e.g. a required constructor argument was missing, a TypeError occurred, or the constructor raised a validation error), and the original exception message is embedded in the new message.

Solutions

Read the embedded original message after 'instantiating the annotation' - it identifies the real constructor failure.
Open the annotation class constructor and verify every required argument is supplied with a compatible type in the annotation usage.
Fix the docblock values: quote strings correctly, use correct scalar types, and ensure required named attributes are present.
If the annotation class is yours, add default values for optional parameters or throw clearer validation errors in the constructor.

Example fix

// before (annotation usage missing required arg)
/** @Route(path="/api") */
// after (constructor requires name)
/** @Route(name="api", path="/api") */

Defensive patterns

Strategy: try-catch

Validate before calling

$ctor = (new ReflectionClass(MyAnnotation::class))->getConstructor();
foreach ($ctor->getParameters() as $p) {
    if (!$p->isOptional() && !$p->isVariadic() && !isset($args[$p->getName()])) {
        throw new LogicException("Missing required annotation argument: {$p->getName()}");
    }
}

Try / catch

try {
    $annot = $reader->getClassAnnotation($ref, MyAnnotation::class);
} catch (AnnotationException $e) {
    if (str_contains($e->getMessage(), 'An error occurred while instantiating')) {
        error_log($e->getMessage()); // includes the nested constructor error
        throw new ConfigException('Bad annotation instantiation: ' . $e->getMessage(), 0, $e);
    }
    throw $e;
}

Prevention

Read the nested message inside the exception for the true constructor failure.
Keep constructor defaults for optional annotation attributes.
Type-validate docblock values against constructor parameter types.
Test annotation parsing of all classes in CI to surface constructor throws early.

When it happens

Trigger: Instantiating an annotation whose constructor throws: a required constructor argument missing from the docblock, a wrong argument type causing TypeError, or an explicit throw inside the annotation constructor (e.g. validating enum values or non-empty strings).

Common situations: Annotation classes converted to readonly promoted properties where parameter defaults were removed; passing wrong scalar types in docblock values; constructor validation asserting constraints that user-supplied docblock data violates; PHP version differences changing constructor signature enforcement.

Related errors

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

Appendix: source

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

        return $values;
    }

    /**
     * Try to instantiate the annotation and catch and process any exceptions related to failure
     *
     * @param class-string        $name
     * @param array<string,mixed> $arguments
     *
     * @return object
     *
     * @throws AnnotationException
     */
    private function instantiateAnnotiation(string $originalName, string $context, string $name, array $arguments)
    {
        try {
            return new $name(...$arguments);
        } catch (Throwable $exception) {
            throw AnnotationException::creationError(
                sprintf(
                    'An error occurred while instantiating the annotation @%s declared on %s: "%s".',
                    $originalName,
                    $context,
                    $exception->getMessage()
                ),
                $exception
            );
        }
    }
}

View on GitHub (pinned to 17815fb6b2)