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).

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

• Cannot download packages because no cache directory is…
• Cannot generate documentation for just one module within a…
• Cannot generate JUnit report for $moduleUri. A report with…
• Cannot substitute output path placeholder
• Cannot write to stdin

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

Appendix: 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)