apple/pkl · error · ProtocolException

Unexpected incoming request message: $message

Error message

Unexpected incoming request message: $message

What it means

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.

Solutions

1. Align client and server pkl versions so supported request sets match.
2. Ensure the client only sends CreateEvaluatorRequest/EvaluateRequest as requests.
3. Fix transport implementations that misroute messages between channels.
4. Log the unexpected message type to diagnose the mismatch.

Example fix

// before (client newer than server)
client.sendRequest(NewerEvaluateRequestV2(...)) // ProtocolException
// after
client.sendRequest(EvaluateRequest(...)) // or upgrade pkl-server

if (message !is CreateEvaluatorRequest && message !is EvaluateRequest) { logger.warn("Unsupported request: ${message::class}"); return }

fun isSupportedRequest(m: Message) = m is CreateEvaluatorRequest || m is EvaluateRequest

try { server.start() } catch (e: ProtocolException) { logger.error("Unsupported request: ${e.message}") }

When it happens

Trigger: 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.

Common situations: Newer client talking to an older pkl-server, custom client code invoking unimplemented requests, transport bugs misrouting one-way messages into the request channel.

Understand the failure class

Background: "invalid response format", "malformed payload", "missing data field": when an API returns 200 but the response shape is wrong — this error's family across 23 libraries.

Related errors

• Unexpected incoming one-way message: $message
• Cannot receive request messages before transport start.
• unknownRequestId
• Cannot receive one-way messages before transport start.
• Failed to create an evaluator. $e

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

Appendix: source

Thrown at pkl-server/src/main/kotlin/org/pkl/server/Server.kt:80

          ::log,
        )
      )
  }

  /** Starts listening to incoming messages */
  fun start() {
    transport.start(
      { message ->
        when (message) {
          is CloseEvaluator -> handleCloseEvaluator(message)
          else -> throw ProtocolException("Unexpected incoming one-way message: $message")
        }
      },
      { message ->
        when (message) {
          is CreateEvaluatorRequest -> handleCreateEvaluator(message)
          is EvaluateRequest -> handleEvaluate(message)
          else -> throw ProtocolException("Unexpected incoming request message: $message")
        }
      },
    )
  }

  /**
   * Stops listening to incoming messages, cancels pending evaluation requests, and releases
   * resources held by this server.
   */
  override fun close() {
    transport.closeQuietly()
    for ((_, evaluator) in evaluators) {
      // if currently in use, blocks until cancellation complete
      evaluator.closeQuietly()
    }
    executor.shutdown()
  }

View on GitHub (pinned to f3efcbfc9b)