apple/pkl · error

cannotFindCollectionElement

cannotFindCollectionElement

Error message

cannotFindCollectionElement

What it means

List.indexOf(elem) returns the 0-based index of the element, but Pkl has no null/-1-safe path in this API: when the element is not present, the runtime throws cannotFindCollectionElement with the 'Element' and 'Collection' attached.

Solutions

1. Check membership first: list.contains(elem) before indexOf
2. Use list.filter((e) -> e == elem).isEmpty handling instead of indexOf
3. Fix the searched value (spelling, type, case) so equality holds
4. Ensure the element was not removed by upstream transformations

Example fix

// before
local idx = fruits.indexOf("banana")
// after
local idx = fruits.contains("banana") ? fruits.indexOf("banana") : -1

if (!list.contains(elem)) throw new Error("element not in list: "+elem)

function canLocate(list, elem) { return list.includes(elem); }

When it happens

Trigger: Calling List.indexOf(value) where value is not present in the list (indexOf internally returns -1 and the node converts it into this error).

Common situations: Searching for a key, enum value, or name removed or renamed in the data; comparing by equality where types differ subtly; expecting an element that an earlier stage filtered out.

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

• cannotFindMatchingCollectionElement
• cannotFindMatchingCollectionElement
• cannotFindModule
• elementIndexOutOfRange
• elementIndexOutOfRange

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

Appendix: source

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

    @Specialization
    protected Object eval(VmList self, VmFunction function) {
      var iterator = self.reverseIterator();
      while (iterator.hasNext()) {
        var elem = iterator.next();
        if (applyLambdaNode.executeBoolean(function, elem)) return elem;
      }
      return VmNull.withoutDefault();
    }
  }

  public abstract static class indexOf extends ExternalMethod1Node {
    @Specialization
    protected long eval(VmList self, Object elem) {
      var result = self.indexOf(elem);
      if (result == -1) {
        CompilerDirectives.transferToInterpreter();
        throw exceptionBuilder()
            .evalError("cannotFindCollectionElement")
            .withProgramValue("Element", elem)
            .withProgramValue("Collection", self)
            .build();
      }
      return result;
    }
  }

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

  public abstract static class lastIndexOf extends ExternalMethod1Node {
    @Specialization

View on GitHub (pinned to f3efcbfc9b)