quarkusio/quarkus · error · IllegalArgumentException

Annotation '${instance}' on '${instance.target()}' contains

Error message

Annotation '${instance}' on '${instance.target()}' contains the following currently unsupported annotation values: ${unsupportedValues}

What it means

The Spring Cache extension supports only a subset of annotation attributes. validateUsage scans the annotation's values against CURRENTLY_UNSUPPORTED_ANNOTATION_VALUES and throws if any unsupported attribute (e.g. 'key', 'condition', 'unless', 'cacheManager') is present. This is a deliberate build-time limitation of the Quarkus implementation rather than Spring semantics.

Source

Thrown at extensions/spring-cache/deployment/src/main/java/io/quarkus/spring/cache/SpringCacheProcessor.java:87

        }
        return result;
    }

    private void validateUsage(AnnotationInstance instance) {
        if (instance.target().kind() != AnnotationTarget.Kind.METHOD) {
            throw new IllegalArgumentException(
                    "Currently Spring Cache annotations can only be added to methods. Offending instance is annotation '"
                            + instance + "' on " + instance.target() + "'");
        }
        List<AnnotationValue> values = instance.values();
        List<String> unsupportedValues = new ArrayList<>();
        for (AnnotationValue value : values) {
            if (CURRENTLY_UNSUPPORTED_ANNOTATION_VALUES.contains(value.name())) {
                unsupportedValues.add(value.name());
            }
        }
        if (!unsupportedValues.isEmpty()) {
            throw new IllegalArgumentException("Annotation '" +
                    instance + "' on '" + instance.target()
                    + "' contains the following currently unsupported annotation values: "
                    + String.join(", ", unsupportedValues));
        }
    }

}

View on GitHub (pinned to e1c734241f)

Solutions

1. Remove the unsupported attributes from the annotation
2. Rely on Quarkus cache-key defaults (method parameters) or implement a custom cache key via the Caffeine/redis-cache extension instead of SpEL keys
3. Move conditional logic (formerly 'condition'/'unless') into the method body

Example fix

// before
@Cacheable(value = "items", key = "#id", unless = "#result == null")
public Item find(long id) { ... }

// after
@Cacheable("items")
public Item find(long id) { ... }

Set<String> unsupported = Set.of("key", "keyGenerator", "condition", "unless", "cacheManager");
for (Annotation ann : method.getAnnotations()) {
    // fail fast in a startup listener if unsupported attributes are used
}

When it happens

Trigger: Using @Cacheable/@CacheEvict/@CachePut with attributes such as key, keyGenerator, condition, unless, or cacheManager in a Quarkus app; the deployment step lists them in the error message.

Common situations: Migrating Spring code that customizes cache keys with SpEL ('key="#id"') or conditional caching ('condition="#name != null"'); users unaware Quarkus only supports the cache-names/values basics.

Related errors

• Currently Spring Cache annotations can only be added to meth
• Quarkus currently only supports using a single cache name. O
• Failed to open path tree with root %s
• Dev services for ${request.getName()} requires a startable s
• Name cannot start with '/':${name}

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/215c043dadb9873f. Report an issue: GitHub.