redis/jedis · error · JedisException

Unknown message type:

Error message

Unknown message type:

What it means

The final else-branch of JedisShardedPubSubBase.process() fires when the reply object is neither a List nor a byte[] — some other type arrived on the sharded pub/sub connection. It throws JedisException("Unknown message type: " + reply), meaning the client cannot classify the incoming object at all.

Solutions

  1. Use RESP3 consistently when token auth or push features are enabled; otherwise ensure RESP2 end-to-end.
  2. Upgrade Jedis so newer reply/push shapes are recognized.
  3. Dedicate the connection to sharded pub/sub and avoid middleware that rewrites RESP.
  4. On catch, close the connection and re-create the subscription from scratch.

Example fix

// before
RedisClient.builder().protocol(RedisProtocol.RESP2).build(); // push frames mis-parsed
// after
RedisClient.builder().protocol(RedisProtocol.RESP3).build(); // push-aware parsing
Defensive patterns

Strategy: try-catch

Validate before calling

boolean protocolSupported(RedisProtocol p) { return p == RedisProtocol.RESP2 || p == RedisProtocol.RESP3; }

Type guard

boolean isClassifiableReply(Object reply) {
  return reply instanceof List || reply instanceof byte[];
}

Try / catch

try {
  shardedPubSub.proceed(jedis, channel);
} catch (JedisException e) {
  if (e.getMessage().startsWith("Unknown message type")) {
    jedis.close(); // rebuild connection with correct protocol
  } else throw e;
}

Prevention

When it happens

Trigger: proceed() receives a reply object that is not a List (pub/sub message) and not a byte[] (command ack) — e.g. a Long, a nested structure, or a RESP3 push-typed object this version doesn't decode.

Common situations: RESP3 push frames reaching a client built for RESP2 parsing; server/proxy sending malformed or novel reply shapes; connection state corruption after a previous error.

Related errors

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

Appendix: source

Thrown at src/main/java/redis/clients/jedis/JedisShardedPubSubBase.java:113

          final T enchannel = (bchannel == null) ? null : encode(bchannel);
          onSUnsubscribe(enchannel, subscribedChannels);
        } else if (Arrays.equals(SMESSAGE.getRaw(), resp)) {
          final byte[] bchannel = (byte[]) listReply.get(1);
          final byte[] bmesg = (byte[]) listReply.get(2);
          final T enchannel = (bchannel == null) ? null : encode(bchannel);
          final T enmesg = (bmesg == null) ? null : encode(bmesg);
          onSMessage(enchannel, enmesg);
        } else {
          throw new JedisException("Unknown message type: " + firstObj);
        }
      } else if (reply instanceof byte[]) {
        Consumer<Object> resultHandler = authenticator.resultHandler.poll();
        if (resultHandler == null) {
          throw new JedisException("Unexpected message : " + SafeEncoder.encode((byte[]) reply));
        }
        resultHandler.accept(reply);
      } else {
        throw new JedisException("Unknown message type: " + reply);
      }
    } while (!Thread.currentThread().isInterrupted() && isSubscribed());

//    /* Invalidate instance since this thread is no longer listening */
//    this.client = null;
  }
}

View on GitHub (pinned to 6dac31d4c2)