redis/jedis · error · IllegalArgumentException

is not supported. Value: " ".

Error message

${key.getClass().getSimpleName()} is not supported. Value: "${String.valueOf(key)}".

What it means

Client-side caching keys must be byte[] or String Redis keys; AbstractCache.makeKeyForRedisKeysToCacheKeys() normalizes them into BufferedKey ByteBuffers for the internal map. Any other key type (e.g. Integer, long-wrapped objects, custom key classes) hits the else branch and throws this IllegalArgumentException naming the key's simple class and its string value.

Solutions

Convert the key to a String (or byte[]) before using it with the cache, e.g. String.valueOf(key) or SafeEncoder.encode(key.toString()).
If using a custom key class, extract its underlying String/byte[] representation at the call site.
Add a guard in your data-access layer enforcing that cache keys are always String or byte[].

Example fix

// before
cache.getKey(12345); // IllegalArgumentException: Integer is not supported
// after
cache.getKey(String.valueOf(12345));

Defensive patterns

Strategy: type-guard

Validate before calling

if (!(key instanceof String) && !(key instanceof byte[])) {
  throw new IllegalArgumentException("cache keys must be String or byte[]: " + key.getClass());
}

Type guard

static ByteBuffer toCacheKey(Object key) {
  if (key instanceof byte[]) return ByteBuffer.wrap((byte[]) key);
  if (key instanceof String) return ByteBuffer.wrap(SafeEncoder.encode((String) key));
  throw new IllegalArgumentException("Unsupported cache key type: " + key.getClass());
}

Try / catch

try {
  cache.getKey(rawKey);
} catch (IllegalArgumentException e) {
  if (e.getMessage().endsWith("is not supported.")) {
    cache.getKey(String.valueOf(rawKey));
  } else {
    throw e;
  }
}

Prevention

Standardize cache keys as String (or byte[]) in a shared key-builder utility.
Avoid passing boxed numerics or custom key wrappers into cache APIs.
Use SafeEncoder.encode() for String-to-bytes conversion to preserve encoding semantics.

When it happens

Trigger: Passing a non-String/non-byte[] key object into cache-facing operations or direct cache access paths that route through mapKey/makeKeyForRedisKeysToCacheKeys (e.g. using Integer or a custom Key type where String keys are expected).

Common situations: Auto-unboxed numeric keys from generic DAO code; custom wrapper key classes passed instead of their toString()/value; mixing a cache API keyed by byte[] with application-level typed keys.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

AI-assisted analysis of redis/jedis@6dac31d4c2 (2026-09-08). Data as JSON: /api/errors/a95e65643ad29761. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/redis/clients/jedis/csc/AbstractCache.java:251

   * <p>
   * This normalization ensures that:
   * <ul>
   *   <li>String key {@code "user:1"} and byte key {@code byte[]{0x75, 0x73, 0x65, 0x72, 0x3a, 0x31}} are treated as equal</li>
   *   <li>Cache invalidation works correctly regardless of whether keys were added as String or byte[]</li>
   *   <li>Type mismatches are caught early with clear error messages</li>
   * </ul>
   *
   * @param key the Redis key (must be {@link String} or {@code byte[]})
   * @return ByteBuffer wrapping the normalized byte representation
   * @throws IllegalArgumentException if key is not {@link String} or {@code byte[]}
   */
  private ByteBuffer makeKeyForRedisKeysToCacheKeys(Object key) {
    if (key instanceof byte[]) {
      return makeKeyForRedisKeysToCacheKeys((byte[]) key);
    } else if (key instanceof String) {
      return makeKeyForRedisKeysToCacheKeys(SafeEncoder.encode((String) key));
    } else {
      throw new IllegalArgumentException(key.getClass().getSimpleName() + " is not supported."
          + " Value: \"" + String.valueOf(key) + "\".");
    }
  }

  /**
   * Wraps a byte array in a ByteBuffer for use as a map key.
   * <p>
   * ByteBuffer provides content-based equality, which is required for proper map key behavior
   * with byte arrays.
   *
   * @param b the byte array to wrap
   * @return ByteBuffer wrapping the byte array
   */
  private static ByteBuffer makeKeyForRedisKeysToCacheKeys(byte[] b) {
    return ByteBuffer.wrap(b);
  }

}

View on GitHub (pinned to 6dac31d4c2)