apple/pkl · error · ProtocolException

Failed to create an evaluator. $e

Error message

Failed to create an evaluator. $e

What it means

createEvaluator builds an EvaluatorConfig via the builder; IllegalArgumentException from invalid builder inputs is converted to a ProtocolException (using e.message when present, else "Failed to create an evaluator. $e"). This surfaces invalid CreateEvaluatorRequest options to the client as a protocol-level failure.

Source

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

          }
        logger = ClientLogger(evaluatorId, transport)
        addModuleKeyFactories(createModuleKeyFactories(message, evaluatorId, resolver))
        addResourceReaders(createResourceReaders(message, evaluatorId, resolver))
        message.env?.let { environmentVariables = it }
        message.properties?.let { externalProperties = it }
        timeout = message.timeout
        moduleCacheDir = message.cacheDir
        message.project?.let { proj ->
          val dependencies = buildDeclaredDependencies(proj.projectFileUri, proj.dependencies, null)
          log("Got dependencies: $dependencies")
          setProjectDependencies(dependencies)
        }
        outputFormat = message.outputFormat
        message.traceMode?.let { traceMode = it }
        build()
      }
    } catch (e: IllegalArgumentException) {
      throw ProtocolException(e.message ?: "Failed to create an evaluator. $e", e)
    } catch (e: IllegalStateException) {
      throw ProtocolException(e.message ?: "Failed to create an evaluator. $e", e)
    }
  }

  private fun createResourceReaders(
    message: CreateEvaluatorRequest,
    evaluatorId: Long,
    modulePathResolver: ModulePathResolver,
  ): List<ResourceReader> = buildList {
    add(ResourceReaders.environmentVariable())
    add(ResourceReaders.externalProperty())
    add(ResourceReaders.file())
    add(ResourceReaders.http())
    add(ResourceReaders.https())
    add(ResourceReaders.pkg())
    add(ResourceReaders.projectpackage())
    add(ResourceReaders.modulePath(modulePathResolver))

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Check the exception message for the exact invalid option and correct it in the request.
2. Validate outputFormat is a supported format string before creating the evaluator.
3. Ensure resource reader URIs and parameters are well-formed.
4. Confirm all numeric options (timeouts, limits) are within legal ranges.

Example fix

// before
request.outputFormat = "yaml2" // invalid format -> IAE
// after
request.outputFormat = "yaml"

require(request.outputFormat in setOf("json", "yaml", "pcf", "xml", "textproto", "plist")) { "Invalid outputFormat" }
request.resourceReaders.forEach { require(it.uri != null) { "resourceReader missing uri" } }

try { client.createEvaluator(request) } catch (e: ProtocolException) { logger.error("Evaluator creation rejected: ${e.message}") }

When it happens

Trigger: handleCreateEvaluator receiving a CreateEvaluatorRequest whose options are invalid — bad resourceReader parameters, invalid outputFormat, illegal timeout or allowedModules values causing the builder's IllegalArgumentException.

Common situations: Clients passing malformed resource reader specs, an unsupported/invalid output format string, or negative durations in evaluator options.

Related errors

• Unexpected end of input; 0 message bytes
• Unexpected incoming one-way message: ${msg}
• Unexpected incoming request message: ${msg}
• malformedMessageHeaderLength
• unhandledMessageCode

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