Netflix/Hystrix · error · HystrixCachingException

return type of cacheKey method must be String. Method: '{}',

Error message

return type of cacheKey method must be String. Method: '{}', Class: '{}'

What it means

A cacheKeyMethod must return java.lang.String, because the generated cache key is a String. Javanica checks cacheKeyMethod.getReturnType().equals(String.class) immediately after resolving the method and throws HystrixCachingException if the return type is anything else (primitives, boxed types, objects, even CharSequence subclasses do not pass — the check is exact-class equality).

Source

Thrown at hystrix-contrib/hystrix-javanica/src/main/java/com/netflix/hystrix/contrib/javanica/cache/CacheInvocationContextFactory.java:78

        if (method.isAnnotationPresent(CacheRemove.class)) {
            CacheRemove cacheRemove = method.getAnnotation(CacheRemove.class);
            MethodExecutionAction cacheKeyMethod = createCacheKeyAction(cacheRemove.cacheKeyMethod(), metaHolder);
            return new CacheInvocationContext<CacheRemove>(cacheRemove, cacheKeyMethod, metaHolder.getObj(), method, metaHolder.getArgs());
        }
        return null;
    }

    private static MethodExecutionAction createCacheKeyAction(String method, MetaHolder metaHolder) {
        MethodExecutionAction cacheKeyAction = null;
        if (StringUtils.isNotBlank(method)) {
            Method cacheKeyMethod = getDeclaredMethod(metaHolder.getObj().getClass(), method,
                    metaHolder.getMethod().getParameterTypes());
            if (cacheKeyMethod == null) {
                throw new HystrixCachingException("method with name '" + method + "' doesn't exist in class '"
                        + metaHolder.getObj().getClass() + "'");
            }
            if (!cacheKeyMethod.getReturnType().equals(String.class)) {
                throw new HystrixCachingException("return type of cacheKey method must be String. Method: '" + method + "', Class: '"
                        + metaHolder.getObj().getClass() + "'");
            }

            MetaHolder cMetaHolder = MetaHolder.builder().obj(metaHolder.getObj()).method(cacheKeyMethod).args(metaHolder.getArgs()).build();
            cacheKeyAction = new MethodExecutionAction(cMetaHolder.getObj(), cacheKeyMethod, cMetaHolder.getArgs(), cMetaHolder);
        }
        return cacheKeyAction;
    }

}

View on GitHub (pinned to 5ce3bc58c3)

Solutions

1. Change the cache key method's return type to exactly String (return String.valueOf(id) where needed).
2. If the helper is shared, add a thin String-returning wrapper and reference that in cacheKeyMethod.
3. Alternatively drop cacheKeyMethod and use @CacheKey parameter annotations to let Javanica build the key.

Example fix

// before
@CacheRemove(commandKey = "getUser", cacheKeyMethod = "keyFor")
public void updateUser(User u) { ... }
private Long keyFor(User u) { return u.getId(); }

// after
@CacheRemove(commandKey = "getUser", cacheKeyMethod = "keyFor")
public void updateUser(User u) { ... }
private String keyFor(User u) { return String.valueOf(u.getId()); }

static void assertCacheKeyMethodReturnsString(Object target, Method annotated, String keyMethodName) throws Exception {
    if (keyMethodName == null || keyMethodName.trim().isEmpty()) return;
    Method m = target.getClass().getMethod(keyMethodName, annotated.getParameterTypes());
    if (!m.getReturnType().equals(String.class))
        throw new IllegalStateException("cacheKeyMethod '" + keyMethodName + "' must return String, returns " + m.getReturnType());
}

catch (HystrixCachingException e) with message 'return type of cacheKey method must be String' → treat as wiring bug: change the helper's return type to String and re-run; do not catch in production code.

When it happens

Trigger: cacheKeyMethod returns int, Long, Object, or a key object type; returning CharSequence or a custom Key class instead of exactly String.

Common situations: Reusing an existing getId()/hashCode() helper as the cache key method; boxing mismatch where the helper returns Integer for an id that is conceptually a string.

Related errors

• method with name '{}' doesn't exist in class '{}'
• Return type of batch method must be java.util.List parametri
• Incompatible return types. \nCommand method: " + commandMeth
• method cannot be annotated with HystrixCommand and HystrixCo
• Collapser method must have one argument: {}

AI-assisted analysis of Netflix/Hystrix@5ce3bc58c3 (2026-08-14). Data as JSON: /api/errors/994312952b5c3867. Report an issue: GitHub.