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

The expression {type} is unknown

Error message

The expression {type} is unknown

What it means

While resolving the parameter expression of an annotation, Phalcon walks the parsed token tree; each node must be a recognized type (integer, string, array, nested annotation, etc.). Hitting the default branch means the parser produced a token type the resolver does not know how to turn into a PHP value, so the annotation expression is not representable.

Source

Thrown at phalcon/Annotations/Annotation.zep:156

                for item in expr["items"] {
                    let resolvedItem = this->getExpression(
                        item["expr"]
                    );

                    if fetch name, item["name"] {
                        let arrayValue[name] = resolvedItem;
                    } else {
                        let arrayValue[] = resolvedItem;
                    }
                }

                return arrayValue;

            case PHANNOT_T_ANNOTATION:
                return new Annotation(expr);

            default:
                throw new UnknownAnnotationExpression(type);
        }

        return value;
    }

    /**
     * Returns the annotation's name
     */
    public function getName() -> null | string
    {
        return this->name;
    }

    /**
     * Returns a named argument
     */
    public function getNamedArgument( string name) -> var | null
    {

View on GitHub (pinned to b7419de9cd)

Solutions

1. Open the docblock named in the stack trace and rewrite the parameter using supported expressions: literals, quoted strings, arrays `{...}`, and nested `@Annotation(...)`
2. Quote unusual values: `@Route(prefix='/api')` instead of bare tokens
3. If you need custom expression types, parse them yourself from the raw annotation arguments rather than inside Phalcon's expression resolver

Example fix

// before (unsupported token sequence)
/** @Route(/api/v1/invoices) */
class InvoicesController {}
// after
/** @Route(prefix='/api/v1/invoices') */
class InvoicesController {}

try {
    $reflector = $annotations->get($className);
} catch (\Phalcon\Annotations\Exceptions\UnknownAnnotationExpression $e) {
    // log the class so the offending docblock can be fixed; fail soft if annotations are optional
    $logger->error('Bad annotation expression in ' . $className . ': ' . $e->getMessage());
    $reflector = null;
}

When it happens

Trigger: A docblock containing an annotation whose parameter uses unsupported syntax, e.g. `@MyAnnotation(value=@foo bar)` or constructs borrowed from other annotation libraries. Raised while reading annotations via `$annotations->get($class)` / `getMethodAnnotations()` on the affected class.

Common situations: Copy-pasting Doctrine-style or JMS-style annotations into a Phalcon project; typos that change token shape (missing quotes, stray characters); upgrading Phalcon across parser token-constant changes.

Related errors

• Cannot read annotation data
• Annotations directory cannot be written
• Collection does not have an annotation called '{name}'
• Invalid WKB: empty value
• Invalid WKB: buffer too short for MySQL prefix

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