{"record":{"id":"779cca297507f151","repo":"apple/pkl","slug":"evaluationtimedout","errorCode":"evaluationTimedOut","errorMessage":"evaluationTimedOut","messagePattern":"evaluationTimedOut","errorType":"error_code","errorClass":"PklException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/EvaluatorImpl.java","lineNumber":480,"sourceCode":"    }\n  }\n\n  private <T> T doEvaluate(ModuleSource moduleSource, Function<VmTyped, T> doEvaluate) {\n    return doEvaluate(\n        () -> {\n          var moduleKey = moduleResolver.resolve(normalizeModuleSource(moduleSource));\n          var module = VmLanguage.get(null).loadModule(moduleKey);\n          return doEvaluate.apply(module);\n        });\n  }\n\n  private void handleTimeout(@Nullable TimeoutTask timeoutTask) {\n    if (timeoutTask == null || timeoutTask.cancel()) return;\n\n    assert timeout != null;\n    // TODO: use a different exception type so that clients can tell apart timeouts from other\n    // errors\n    throw new PklException(\n        ErrorMessages.create(\n            \"evaluationTimedOut\", (timeout.getSeconds() + timeout.getNano() / 1_000_000_000d)));\n  }\n\n  private VmException moduleOutputValueTypeMismatch(\n      VmTyped module, PClassInfo<?> expectedClassInfo, Object value, VmTyped output) {\n    var moduleUri = module.getModuleInfo().getModuleKey().getUri();\n    var builder =\n        new VmExceptionBuilder()\n            .evalError(\n                \"invalidModuleOutput\",\n                \"output.value\",\n                expectedClassInfo.getDisplayName(),\n                VmUtils.getClass(value).getPClassInfo().getDisplayName(),\n                moduleUri);\n    var outputValueMember = output.getMember(Identifier.VALUE);\n    assert outputValueMember != null;\n    var uriOfValueMember = outputValueMember.getSourceSection().getSource().getURI();","sourceCodeStart":462,"sourceCodeEnd":498,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/EvaluatorImpl.java#L462-L498","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Increase the timeout via EvaluatorBuilder.timeout(Duration.ofMinutes(...)) or CLI --timeout.","Profile/optimize the Pkl code: hoist repeated computations, avoid quadratic loops, reduce data volume.","Check for slow external module fetches (cache dependencies, e.g. pkl project resolve or JavaMesageResolver caching).","Match on the evaluationTimedOut message code when catching PklException, since there is no dedicated exception type."],"exampleFix":"// before\nEvaluator.builder(moduleSource).build();\n// after\nEvaluator.builder(moduleSource)\n    .setTimeout(Duration.ofMinutes(5))\n    .build();","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  return evaluator.evaluateOutputText(source);\n} catch (PklException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"evaluationTimedOut\")) {\n    // retry with a larger timeout or fail fast\n    throw new EvaluationTimeoutException(e);\n  }\n  throw e;\n}","preventionTips":["Set an explicit, generous timeout matching workload size","Keep Pkl code free of unbounded loops and quadratic operations","Cache resolved dependencies so fetch time doesn't count against evaluation","Monitor evaluation durations in CI to size timeouts"],"tags":["timeout","evaluation"],"backgroundTag":"request-timeout","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}