apple/pkl · error · PklException

evaluationTimedOut

evaluationTimedOut

Error message

evaluationTimedOut

What it means

evaluationTimedOut is thrown by EvaluatorImpl.handleTimeout when a Pkl evaluation exceeds the configured timeout Duration. The evaluator interrupts the running evaluation (cancelling the TimeoutTask is the only case where it returns silently) and raises PklException with the elapsed timeout in seconds. Clients cannot currently distinguish it from other PklExceptions by type (noted TODO in source), only by message code evaluationTimedOut.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/EvaluatorImpl.java:480

    }
  }

  private <T> T doEvaluate(ModuleSource moduleSource, Function<VmTyped, T> doEvaluate) {
    return doEvaluate(
        () -> {
          var moduleKey = moduleResolver.resolve(normalizeModuleSource(moduleSource));
          var module = VmLanguage.get(null).loadModule(moduleKey);
          return doEvaluate.apply(module);
        });
  }

  private void handleTimeout(@Nullable TimeoutTask timeoutTask) {
    if (timeoutTask == null || timeoutTask.cancel()) return;

    assert timeout != null;
    // TODO: use a different exception type so that clients can tell apart timeouts from other
    // errors
    throw new PklException(
        ErrorMessages.create(
            "evaluationTimedOut", (timeout.getSeconds() + timeout.getNano() / 1_000_000_000d)));
  }

  private VmException moduleOutputValueTypeMismatch(
      VmTyped module, PClassInfo<?> expectedClassInfo, Object value, VmTyped output) {
    var moduleUri = module.getModuleInfo().getModuleKey().getUri();
    var builder =
        new VmExceptionBuilder()
            .evalError(
                "invalidModuleOutput",
                "output.value",
                expectedClassInfo.getDisplayName(),
                VmUtils.getClass(value).getPClassInfo().getDisplayName(),
                moduleUri);
    var outputValueMember = output.getMember(Identifier.VALUE);
    assert outputValueMember != null;
    var uriOfValueMember = outputValueMember.getSourceSection().getSource().getURI();

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Increase the timeout via EvaluatorBuilder.timeout(Duration.ofMinutes(...)) or CLI --timeout.
2. Profile/optimize the Pkl code: hoist repeated computations, avoid quadratic loops, reduce data volume.
3. Check for slow external module fetches (cache dependencies, e.g. pkl project resolve or JavaMesageResolver caching).
4. Match on the evaluationTimedOut message code when catching PklException, since there is no dedicated exception type.

Example fix

// before
Evaluator.builder(moduleSource).build();
// after
Evaluator.builder(moduleSource)
    .setTimeout(Duration.ofMinutes(5))
    .build();

try {
  return evaluator.evaluateOutputText(source);
} catch (PklException e) {
  if (e.getMessage() != null && e.getMessage().contains("evaluationTimedOut")) {
    // retry with a larger timeout or fail fast
    throw new EvaluationTimeoutException(e);
  }
  throw e;
}

When it happens

Trigger: Creating an evaluator with EvaluatorBuilder.timeout(Duration) (or useLowLatencyCache/CLI --timeout) and evaluating a module that takes longer than that duration — e.g. huge data sets, deep object hierarchies, expensive computations, or external-reader/module fetch stalls.

Common situations: Default or tight timeout used on large codegen jobs; evaluation accidentally doing unbounded work (huge collections, regex-like blowups); slow network module loads counted against the timeout; CI runners with constrained CPU.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• undefinedPropertyValue

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