apple/pkl · error · CliException

CliException(e.message!!)

Error message

CliException(e.message!!)

What it means

CliServer.doRun starts an evaluation server over stdin/stdout via Server.stream(). If the server raises a ProtocolException — meaning the client speaking the Pkl server protocol sent malformed or unexpected messages — the server wraps it in a CliException using the protocol error's message. This is how the CLI surfaces protocol-level violations to the host process (e.g. an editor extension driving the server).

Source

Thrown at pkl-cli/src/main/kotlin/org/pkl/cli/CliServer.kt:30

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.pkl.cli

import org.pkl.commons.cli.CliBaseOptions
import org.pkl.commons.cli.CliCommand
import org.pkl.commons.cli.CliException
import org.pkl.core.messaging.ProtocolException
import org.pkl.server.Server

class CliServer(options: CliBaseOptions) : CliCommand(options) {
  override fun doRun(): Unit =
    try {
      val server = Server.stream(System.`in`, System.out)
      server.use { it.start() }
    } catch (e: ProtocolException) {
      throw CliException(e.message!!)
    }
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Check that the client driving the server matches the Pkl server protocol version of the installed CLI; upgrade the client or CLI so both sides agree.
2. Inspect the exception message (it is the raw ProtocolException message) to find which message/step the client got wrong, and fix the client's serialization/framing.
3. Verify the process piping stdin is not being truncated or closed early (broken pipe from the parent process).
4. If writing a custom client, validate messages against the protocol spec before writing to stdin.

Example fix

// before: client sends hand-rolled JSON over stdin
process.stdin.write(JSON.stringify({ cmd: "eval" }))

// after: use the official protocol client library matching the CLI version
val client = PklServerClient.connect(process) // emits protocol-compliant messages

// when driving `pkl server` programmatically
try {
  serverProcess.startAndCommunicate()
} catch (e: CliException) {
  // e.message carries the underlying ProtocolException detail;
  // log it and verify client/CLI protocol version compatibility
  logger.error("Pkl server protocol violation: ${e.message}")
}

When it happens

Trigger: Running `pkl server` (Server.stream(System.in, System.out)) when the peer writes bytes that violate the Pkl server protocol: invalid message framing, unknown message types, out-of-order requests, or premature EOF mid-message.

Common situations: An editor plugin or tooling client built against a different protocol version drives `pkl server`; a harness pipes garbage or truncated input into stdin; a bug in a custom client sends responses the server never expects.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Unexpected end of input; 0 message bytes
• Unexpected incoming one-way message: ${msg}
• Unexpected incoming request message: ${msg}
• +e.getMessage()
• Output path `$outputDir` exists and is not a directory.

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