{"record":{"id":"4c46bc5c20d8aa68","repo":"doctrine/annotations","slug":"an-error-occurred-while-instantiating-the-annotation-s","errorCode":null,"errorMessage":"An error occurred while instantiating the annotation @%s declared on %s: \"%s\".","messagePattern":"An error occurred while instantiating the annotation @(.+?) declared on (.+?): \"(.+?)\"\\.","errorType":"exception","errorClass":"AnnotationException","httpStatus":null,"severity":"error","filePath":"lib/Doctrine/Common/Annotations/DocParser.php","lineNumber":1485,"sourceCode":"        return $values;\n    }\n\n    /**\n     * Try to instantiate the annotation and catch and process any exceptions related to failure\n     *\n     * @param class-string        $name\n     * @param array<string,mixed> $arguments\n     *\n     * @return object\n     *\n     * @throws AnnotationException\n     */\n    private function instantiateAnnotiation(string $originalName, string $context, string $name, array $arguments)\n    {\n        try {\n            return new $name(...$arguments);\n        } catch (Throwable $exception) {\n            throw AnnotationException::creationError(\n                sprintf(\n                    'An error occurred while instantiating the annotation @%s declared on %s: \"%s\".',\n                    $originalName,\n                    $context,\n                    $exception->getMessage()\n                ),\n                $exception\n            );\n        }\n    }\n}\n","sourceCodeStart":1467,"sourceCodeEnd":1497,"githubUrl":"https://github.com/doctrine/annotations/blob/17815fb6b2f4c3c701ba2abdf2c6c97b219fb2e4/lib/Doctrine/Common/Annotations/DocParser.php#L1467-L1497","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before (annotation usage missing required arg)\n/** @Route(path=\"/api\") */\n// after (constructor requires name)\n/** @Route(name=\"api\", path=\"/api\") */","handlingStrategy":"try-catch","validationCode":"$ctor = (new ReflectionClass(MyAnnotation::class))->getConstructor();\nforeach ($ctor->getParameters() as $p) {\n    if (!$p->isOptional() && !$p->isVariadic() && !isset($args[$p->getName()])) {\n        throw new LogicException(\"Missing required annotation argument: {$p->getName()}\");\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    $annot = $reader->getClassAnnotation($ref, MyAnnotation::class);\n} catch (AnnotationException $e) {\n    if (str_contains($e->getMessage(), 'An error occurred while instantiating')) {\n        error_log($e->getMessage()); // includes the nested constructor error\n        throw new ConfigException('Bad annotation instantiation: ' . $e->getMessage(), 0, $e);\n    }\n    throw $e;\n}","preventionTips":["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."],"tags":["php","doctrine-annotations","constructor","reflection"],"backgroundTag":"invalid-constructor-argument","analyzedSha":"17815fb6b2f4c3c701ba2abdf2c6c97b219fb2e4","analyzedAt":"2026-09-15T20:30:41.547Z","contentChangedAt":"2026-09-15T20:30:41.547Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}