apple/pkl · error

cannotFindMatchingCollectionElement

cannotFindMatchingCollectionElement

Error message

cannotFindMatchingCollectionElement

What it means

List.find(function) returns the first element satisfying the predicate. If no element matches, Pkl throws cannotFindMatchingCollectionElement instead of returning null, because the Pkl language has no null value. The collection is attached for debugging.

Solutions

1. Guard with a length/predicate pre-check: list.filter(...).isEmpty before find
2. Use List.firstOrNull-style alternatives via fold or filter(...).isEmpty handling in Pkl code
3. Restructure to use filter and handle an empty result explicitly
4. Fix the predicate or ensure the expected element exists in the data

Example fix

// before
local entry = servers.find((s) -> s.name == "db")
// after
local matches = servers.filter((s) -> s.name == "db")
local entry = matches.isEmpty ? defaultServer : matches.first

if (list.filter(pred).isEmpty) throw new Error("no element matches predicate")

function hasMatch(list, pred) { return list.some(pred); }

When it happens

Trigger: Calling List.find((e) -> ...) where the predicate returns false for every element of an empty or non-matching list.

Common situations: Looking up a record in a config list by key/id that is absent after data changes; filtering assumptions broken by upstream data edits; searching an empty list.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• cannotFindCollectionElement
• elementIndexOutOfRange
• elementIndexOutOfRange
• type mismatch: value is not of type List
• abstractMemberCannotHaveBody

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

Appendix: source

Thrown at pkl-core/src/main/java/org/pkl/core/stdlib/base/ListNodes.java:238

  public abstract static class contains extends ExternalMethod1Node {
    @Specialization
    protected boolean eval(VmList self, Object element) {
      return self.contains(element);
    }
  }

  public abstract static class find extends ExternalMethod1Node {
    @Child private ApplyVmFunction1Node applyLambdaNode = ApplyVmFunction1Node.create();

    @Specialization
    protected Object eval(VmList self, VmFunction function) {
      for (var elem : self) {
        if (applyLambdaNode.executeBoolean(function, elem)) return elem;
      }

      CompilerDirectives.transferToInterpreter();
      throw exceptionBuilder()
          .evalError("cannotFindMatchingCollectionElement")
          .withProgramValue("Collection", self)
          .build();
    }
  }

  public abstract static class findOrNull extends ExternalMethod1Node {
    @Child private ApplyVmFunction1Node applyLambdaNode = ApplyVmFunction1Node.create();

    @Specialization
    protected Object eval(VmList self, VmFunction function) {
      for (var elem : self) {
        if (applyLambdaNode.executeBoolean(function, elem)) return elem;
      }
      return VmNull.withoutDefault();
    }
  }

View on GitHub (pinned to f3efcbfc9b)