{"record":{"id":"137da0e837deccd2","repo":"apple/pkl","slug":"unexpected-incoming-request-message-message","errorCode":null,"errorMessage":"Unexpected incoming request message: $message","messagePattern":"Unexpected incoming request message: \\$message","errorType":"exception","errorClass":"ProtocolException","httpStatus":null,"severity":"error","filePath":"pkl-server/src/main/kotlin/org/pkl/server/Server.kt","lineNumber":80,"sourceCode":"          ::log,\n        )\n      )\n  }\n\n  /** Starts listening to incoming messages */\n  fun start() {\n    transport.start(\n      { message ->\n        when (message) {\n          is CloseEvaluator -> handleCloseEvaluator(message)\n          else -> throw ProtocolException(\"Unexpected incoming one-way message: $message\")\n        }\n      },\n      { message ->\n        when (message) {\n          is CreateEvaluatorRequest -> handleCreateEvaluator(message)\n          is EvaluateRequest -> handleEvaluate(message)\n          else -> throw ProtocolException(\"Unexpected incoming request message: $message\")\n        }\n      },\n    )\n  }\n\n  /**\n   * Stops listening to incoming messages, cancels pending evaluation requests, and releases\n   * resources held by this server.\n   */\n  override fun close() {\n    transport.closeQuietly()\n    for ((_, evaluator) in evaluators) {\n      // if currently in use, blocks until cancellation complete\n      evaluator.closeQuietly()\n    }\n    executor.shutdown()\n  }\n","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-server/src/main/kotlin/org/pkl/server/Server.kt#L62-L98","documentation":"The server's request-message handler accepts only CreateEvaluatorRequest and EvaluateRequest; any other request message is a protocol violation and throws ProtocolException. This indicates the client sent a request the server does not implement or from a newer/older protocol version.","triggerScenarios":"Transport's request callback receiving a message type other than CreateEvaluatorRequest or EvaluateRequest, e.g. a client calling an unsupported request API or protocol mismatch.","commonSituations":"Newer client talking to an older pkl-server, custom client code invoking unimplemented requests, transport bugs misrouting one-way messages into the request channel.","solutions":["Align client and server pkl versions so supported request sets match.","Ensure the client only sends CreateEvaluatorRequest/EvaluateRequest as requests.","Fix transport implementations that misroute messages between channels.","Log the unexpected message type to diagnose the mismatch."],"exampleFix":"// before (client newer than server)\nclient.sendRequest(NewerEvaluateRequestV2(...)) // ProtocolException\n// after\nclient.sendRequest(EvaluateRequest(...)) // or upgrade pkl-server","handlingStrategy":"type-guard","validationCode":"if (message !is CreateEvaluatorRequest && message !is EvaluateRequest) { logger.warn(\"Unsupported request: ${message::class}\"); return }","typeGuard":"fun isSupportedRequest(m: Message) = m is CreateEvaluatorRequest || m is EvaluateRequest","tryCatchPattern":"try { server.start() } catch (e: ProtocolException) { logger.error(\"Unsupported request: ${e.message}\") }","preventionTips":["Upgrade client and server together","Check protocol capability negotiation before sending new request types","Route one-way vs request messages correctly in transports","Version-gate new request types on both ends"],"tags":["protocol","server","messaging"],"backgroundTag":"unexpected-api-response-shape","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}