spring-projects/spring-framework · error · IllegalStateException

Unknown annotation type: {annotation}

Error message

Unknown annotation type: {annotation}

What it means

Thrown as an IllegalStateException from AspectJAnnotation.determineAnnotationType() when the annotation's runtime class is not one of the six known AspectJ types in the annotationTypeMap (Pointcut, Around, Before, After, AfterReturning, AfterThrowing). Because findAspectJAnnotationOnMethod already restricts to exactly those six types, reaching this branch indicates an internal invariant violation rather than a normal user error.

Source

Thrown at spring-aop/src/main/java/org/springframework/aop/aspectj/annotation/AbstractAspectJAdvisorFactory.java:198

		public AspectJAnnotation(Annotation annotation) {
			this.annotation = annotation;
			this.annotationType = determineAnnotationType(annotation);
			try {
				this.pointcutExpression = resolvePointcutExpression(annotation);
				Object argNames = AnnotationUtils.getValue(annotation, "argNames");
				this.argumentNames = (argNames instanceof String names ? names : "");
			}
			catch (Exception ex) {
				throw new IllegalArgumentException(annotation + " is not a valid AspectJ annotation", ex);
			}
		}

		private AspectJAnnotationType determineAnnotationType(Annotation annotation) {
			AspectJAnnotationType type = annotationTypeMap.get(annotation.annotationType());
			if (type != null) {
				return type;
			}
			throw new IllegalStateException("Unknown annotation type: " + annotation);
		}

		private String resolvePointcutExpression(Annotation annotation) {
			for (String attributeName : EXPRESSION_ATTRIBUTES) {
				Object val = AnnotationUtils.getValue(annotation, attributeName);
				if (val instanceof String str && !str.isEmpty()) {
					return str;
				}
			}
			throw new IllegalStateException("Failed to resolve pointcut expression in: " + annotation);
		}

		public AspectJAnnotationType getAnnotationType() {
			return this.annotationType;
		}

		public Annotation getAnnotation() {
			return this.annotation;

View on GitHub (pinned to 69bf83ad71)

Solutions

1. Do not instantiate AspectJAnnotation directly; rely on findAspectJAnnotationOnMethod which only accepts the six known annotation types.
2. If extending the framework, ensure you pass only the six recognized AspectJ annotation types.
3. Upgrade Spring to a version that maps the AspectJ annotation type you are using.
4. Report as a Spring bug if reached through normal API usage.

// This error is an internal invariant violation. Defense = do not construct AspectJAnnotation
// with annotations outside the six known types. Prefer the public path:
import org.springframework.aop.aspectj.annotation.AbstractAspectJAdvisorFactory;

// Use the factory's own discovery rather than constructing AspectJAnnotation directly:
// AbstractAspectJAdvisorFactory.findAspectJAnnotationOnMethod(method) returns null for unknown types.

import org.aspectj.lang.annotation.*;
import java.util.Set;

public static boolean isKnownAspectJAnnotationType(Class<? extends java.lang.annotation.Annotation> t) {
    return Set.of(Pointcut.class, Around.class, Before.class, After.class,
                  AfterReturning.class, AfterThrowing.class).contains(t);
}

try {
    List<Advisor> advisors = advisorFactory.getAdvisors(factory);
} catch (IllegalStateException ex) {
    if (ex.getMessage().startsWith("Unknown annotation type")) {
        // collect details and report to Spring; should be unreachable
    } else throw ex;
}

When it happens

Trigger: Construction of an AspectJAnnotation wrapper with an Annotation instance whose type is not in the known map (should not happen via the public factory path); a custom subclass that bypasses findAspectJAnnotationOnMethod and passes an arbitrary annotation into AspectJAnnotation; concurrent modification or a future AspectJ annotation type added without updating the map.

Common situations: Library/framework code that extends AbstractAspectJAdvisorFactory and instantiates AspectJAnnotation directly with a non-standard annotation; an AspectJ version mismatch introducing a new advice annotation not yet mapped by Spring; test code constructing AspectJAnnotation with a mock annotation.

Related errors

• {aspectClass.getName()} is not an @AspectJ aspect
• {annotation} is not a valid AspectJ annotation
• Advice must be declared inside an aspect type: Offending met
• Unsupported advice type on method: {candidateAdviceMethod}
• MethodInvocation is not a Spring ProxyMethodInvocation: {}

AI-assisted analysis of spring-projects/spring-framework@69bf83ad71 (2026-08-09). Data as JSON: /api/errors/c3380b42be640483. Report an issue: GitHub.