phalcon/cphalcon · error · Phalcon\Annotations\Exceptions\AnnotationNotFound

Collection does not have an annotation called '{name}'

Error message

Collection does not have an annotation called '{name}'

What it means

Phalcon\Annotations\Collection::get(name) linearly scans the annotations collected for a class/method/property and returns the first whose name matches. If none matches it throws AnnotationNotFound — the requested annotation simply is not present on that reflection target.

Source

Thrown at phalcon/Annotations/Collection.zep:99

        return annotation;
    }

    /**
     * Returns the first annotation that match a name
     */
    public function get(string name) -> <Annotation>
    {
        var annotation, annotations;

        let annotations = this->annotations;

        for annotation in annotations {
            if name == annotation->getName() {
                return annotation;
            }
        }

        throw new AnnotationNotFound(name);
    }

    /**
     * Returns all the annotations that match a name
     */
    public function getAll(string name) -> <Annotation[]>
    {
        var annotations, annotation;
        array found;

        let found = [],
            annotations = this->annotations;

        for annotation in annotations {
            if name == annotation->getName() {
                let found[] = annotation;
            }
        }

View on GitHub (pinned to b7419de9cd)

Solutions

1. Guard with `$collection->has('Cached')` before calling get()
2. Use `$collection->getAll('Cached')` and check the count when multiple same-name annotations may exist
3. Dump `$collection->getAnnotations()` to see the exact names/case actually parsed, and fix the spelling at either end

Example fix

// before
$ann = $collection->get('Cached');
// after
$ann = $collection->has('Cached') ? $collection->get('Cached') : null;

if ($collection->has('Cached')) {
    $annotation = $collection->get('Cached');
} else {
    $annotation = null;
}

function hasAnnotation(\Phalcon\Annotations\Collection $collection, string $name): bool
{
    return $collection->has($name);
}

try {
    $annotation = $collection->get('Cached');
} catch (\Phalcon\Annotations\Exceptions\AnnotationNotFound $e) {
    $annotation = null; // optional behavior
}

When it happens

Trigger: `$collection->get('Cached')` where the target's docblock has no `@Cached` annotation; name case mismatch ('Cached' vs 'cached', comparison is exact); asking an object for an annotation only defined on a parent class (Phalcon reads only the declared docblock by default).

Common situations: Optional-behavior code assuming an annotation always exists; renaming an annotation without updating consumers; expecting inherited annotations to be visible; case differences between teams.

Related errors

• The collection '{name}' does not exist in the manager
• Cannot read annotation data
• Annotations directory cannot be written
• The expression {type} is unknown
• Module '{name}' is not registered in the application

AI-assisted analysis of phalcon/cphalcon@b7419de9cd (2026-08-21). Data as JSON: /api/errors/762f0b72cd0edb27. Report an issue: GitHub.