apple/pkl · error · ProtocolException

unhandledMessageType

unhandledMessageType

Error message

unhandledMessageType

What it means

The encoder's encodeMessage switch has no case for the given message type, so it throws ProtocolException with code unhandledMessageType naming the type. This is an internal exhaustiveness guard when a new message Type is added without encoder support.

Solutions

1. Upgrade pkl so encoder and message Type definitions are in sync
2. Add a switch case packing the new message type's fields
3. Filter out unsupported message types before calling encodeMessage
4. Route custom types through a dedicated encoder instead

Example fix

// before
default -> throw new ProtocolException(ErrorMessages.create("unhandledMessageType", msg.type().toString()));
// after
case CAN_EVALUATE -> { packHeader(m.type()); packKeyValue("supportedFeatures", ...); }
default -> throw new ProtocolException(ErrorMessages.create("unhandledMessageType", msg.type().toString()));

static boolean isEncodable(Message m) { return java.util.Set.of(Type.EVALUATE, Type.CANCEL_EVALUATE, Type.LOG, ...).contains(m.type()); }

static boolean canEncode(Message m) { return switch (m.type()) { case EVALUATE, CANCEL_EVALUATE, LOG, READ, OUTDATED -> true; default -> false; }; }

try { encoder.encodeMessage(msg); } catch (ProtocolException e) { if (String.valueOf(e.getMessage()).contains("unhandledMessageType")) { /* upgrade pkl or drop this message type */ } throw e; }

When it happens

Trigger: Calling BaseMessagePackEncoder.encodeMessage with a Message whose type() is not covered by the switch (e.g. a newly added or custom message type).

Common situations: Library upgrades where a new message type was introduced but the encoder (or a subclass overriding encodeMessage) was not updated; custom message types passed to the standard encoder.

Related errors

• malformedMessageHeaderLength
• unhandledMessageCode
• Cannot receive request messages before transport start.
• characterCodingException
• Expected structure to have at least slots, found

AI-assisted analysis of apple/pkl@f3efcbfc9b (2026-09-08). Data as JSON: /api/errors/a378e603bcde57fd. Report an issue: GitHub.

Appendix: source

Thrown at pkl-core/src/main/java/org/pkl/core/messaging/BaseMessagePackEncoder.java:131

        packKeyValue("evaluatorId", m.evaluatorId());
        packKeyValue("uri", m.uri().toString());
      }
      case LIST_MODULES_RESPONSE -> {
        var m = (ListModulesResponse) msg;
        packMapHeader(2, m.pathElements(), m.error());
        packKeyValue("requestId", m.requestId());
        packKeyValue("evaluatorId", m.evaluatorId());
        if (m.pathElements() != null) {
          packer.packString("pathElements");
          packer.packArrayHeader(m.pathElements().size());
          for (var pathElement : m.pathElements()) {
            packPathElement(pathElement);
          }
        }
        packKeyValue("error", m.error());
      }
      default ->
          throw new ProtocolException(
              ErrorMessages.create("unhandledMessageType", msg.type().toString()));
    }
  }
}

View on GitHub (pinned to f3efcbfc9b)