redis/jedis · error · IllegalArgumentException

Unknown stream entry deletion result code

Error message

Unknown stream entry deletion result code: ${code}

What it means

StreamEntryDeletionResult.fromCode converts an integer result code returned by Redis's XDELEX/XACKDEL commands into the enum. This IllegalArgumentException is thrown when the server returns a code the client does not recognize (anything outside 0,1,2), typically meaning the client's enum predates a newer Redis server version or the protocol changed.

Solutions

1. Upgrade Jedis to the latest release so the enum maps all codes your Redis server can return
2. Pin your Redis server to a version whose XDELEX/XACKDEL result codes are covered by your Jedis version
3. Wrap the call in try-catch for IllegalArgumentException and treat unknown codes conservatively (e.g. re-check entry existence)

Example fix

// before (older Jedis)
StreamEntryDeletionResult r = StreamEntryDeletionResult.fromLong(result);
// after (upgrade dependency, or guard)
try {
  StreamEntryDeletionResult r = StreamEntryDeletionResult.fromLong(result);
} catch (IllegalArgumentException e) {
  // unknown code: fall back to explicit existence check
}

if (reply == null || !(reply instanceof Long)) throw new IllegalStateException("unexpected XDELEX reply");
if (!List.of(0L,1L,2L).contains((Long) reply)) { /* treat as unknown, handle explicitly */ }

try {
  StreamEntryDeletionResult r = StreamEntryDeletionResult.fromLong(longReply);
} catch (IllegalArgumentException e) {
  // log code, fall back to NOT_FOUND-like handling or XPENDING/exists check
}

When it happens

Trigger: Calling XDELEX/XACKDEL (via stream entry deletion APIs) against a Redis server that returns an unmapped result code for an entry, e.g. a new code added by a newer server release while the Jedis version only knows 0=NOT_FOUND, 1=DELETED, 2=NOT_DELETED_UNACKNOWLEDGED_OR_STILL_REFERENCED.

Common situations: Running a newer Redis (e.g. Redis 8.x with extended deletion semantics) with an older Jedis; custom/proxy Redis implementations returning non-standard codes; protocol regressions after upgrades.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Stream entry deletion result value cannot be null
• null is not a valid argument.
• " " is not a valid argument.
• Failed to create socket.
• HashImport ' ' has been discarded

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

Appendix: source

Thrown at src/main/java/redis/clients/jedis/resps/StreamEntryDeletionResult.java:67

    return code;
  }

  /**
   * Creates a StreamEntryDeletionResult from the numeric code returned by Redis.
   * @param code the numeric code from Redis
   * @return the corresponding StreamEntryDeletionResult
   * @throws IllegalArgumentException if the code is not recognized
   */
  public static StreamEntryDeletionResult fromCode(int code) {
    switch (code) {
      case -1:
        return NOT_FOUND;
      case 1:
        return DELETED;
      case 2:
        return NOT_DELETED_UNACKNOWLEDGED_OR_STILL_REFERENCED;
      default:
        throw new IllegalArgumentException("Unknown stream entry deletion result code: " + code);
    }
  }

  /**
   * Creates a StreamEntryDeletionResult from a Long value returned by Redis.
   * @param value the Long value from Redis
   * @return the corresponding StreamEntryDeletionResult
   * @throws IllegalArgumentException if the value is null or not recognized
   */
  public static StreamEntryDeletionResult fromLong(Long value) {
    if (value == null) {
      throw new IllegalArgumentException("Stream entry deletion result value cannot be null");
    }
    return fromCode(value.intValue());
  }

  @Override
  public String toString() {

View on GitHub (pinned to 6dac31d4c2)