{"record":{"id":"547bb0886b2d6d55","repo":"apple/pkl","slug":"expectedsingleelementcollection","errorCode":"expectedSingleElementCollection","errorMessage":"expectedSingleElementCollection","messagePattern":"expectedSingleElementCollection","errorType":"error_code","errorClass":"VmException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/runtime/VmCollection.java","lineNumber":65,"sourceCode":"  public abstract Builder<? extends VmCollection> builder();\n\n  public final void checkNonEmpty() {\n    if (isEmpty()) {\n      CompilerDirectives.transferToInterpreter();\n      throw new VmExceptionBuilder()\n          .evalError(\"expectedNonEmptyCollection\")\n          .withProgramValue(\"Collection\", this)\n          .build();\n    }\n  }\n\n  @SuppressWarnings(\"BooleanMethodIsAlwaysInverted\")\n  public abstract boolean isLengthOne();\n\n  public final void checkLengthOne() {\n    if (!isLengthOne()) {\n      CompilerDirectives.transferToInterpreter();\n      throw new VmExceptionBuilder()\n          .evalError(\"expectedSingleElementCollection\")\n          .withProgramValue(\"Collection\", this)\n          .build();\n    }\n  }\n\n  protected static void checkPositive(long n) {\n    VmUtils.checkPositive(n);\n  }\n\n  @TruffleBoundary\n  public final boolean startsWith(VmCollection other) {\n    if (getLength() < other.getLength()) return false;\n\n    var iter = iterator();\n    var otherIter = other.iterator();\n\n    //noinspection WhileLoopReplaceableByForEach","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/runtime/VmCollection.java#L47-L83","documentation":"Thrown by VmCollection.checkLengthOne() when a Pkl collection does not contain exactly one element. Pkl throws it where code expects a single-element collection and calls an operation (like converting to a single value) that only makes sense with exactly one element. The collection itself is attached as program value 'Collection'.","triggerScenarios":"Calling checkLengthOne() on a collection with 0 or 2+ elements; e.g. evaluating an operation that requires a singleton collection such as flattening contexts or implicit element extraction from a collection.","commonSituations":"Expecting a listing to match exactly one file/glob result but getting zero or multiple matches; passing a List/Set/Mapping with several elements where a single element is required.","solutions":["Inspect the collection reported in the 'Collection' program value and determine why it has != 1 elements","If multiple values are possible, index the collection explicitly (e.g. lst[0]) or pick the desired element","If zero elements are possible, add a null/empty check before the operation","Fix the upstream data or glob pattern so it yields exactly one element"],"exampleFix":"// before\nvalue = someListing.first\n// after\nvalue = if (someListing.isEmpty) throw(\"expected exactly one element\") else someListing.first","handlingStrategy":"validation","validationCode":"if (coll.length == 1) { /* proceed */ } else { throw \"expected exactly one element, got \\(coll.length)\" }","typeGuard":"function isSingleton<T>(c: Iterable<T>): boolean { return c.size === 1 }","tryCatchPattern":null,"preventionTips":["Check collection length before single-element operations","Handle empty results from globs/filters explicitly","Index explicitly (first/last) instead of relying on implicit singleton extraction"],"tags":["pkl","collection","validation"],"backgroundTag":"invalid-argument-value","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}