{"record":{"id":"69b8cc54eb70e681","repo":"apple/pkl","slug":"expectedsingleelementlisting","errorCode":"expectedSingleElementListing","errorMessage":"expectedSingleElementListing","messagePattern":"expectedSingleElementListing","errorType":"error_code","errorClass":"VmException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/stdlib/base/ListingNodes.java","lineNumber":342,"sourceCode":"          });\n      return builder.build();\n    }\n  }\n\n  private static void checkNonEmpty(VmListing self, PklNode node) {\n    if (self.isEmpty()) {\n      CompilerDirectives.transferToInterpreter();\n      throw new VmExceptionBuilder()\n          .evalError(\"expectedNonEmptyListing\")\n          .withLocation(node)\n          .build();\n    }\n  }\n\n  private static void checkSingleton(VmListing self, PklNode node) {\n    if (self.getLength() != 1) {\n      CompilerDirectives.transferToInterpreter();\n      throw new VmExceptionBuilder()\n          .evalError(\"expectedSingleElementListing\")\n          .withLocation(node)\n          .build();\n    }\n  }\n}\n","sourceCodeStart":324,"sourceCodeEnd":349,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/stdlib/base/ListingNodes.java#L324-L349","documentation":"Listing members that require exactly one element (such as the implicit single-element conversion or members like `first` used in single-element context) throw expectedSingleElementListing when the listing's length is not 1. checkSingleton validates length == 1 and reports at the accessing node.","triggerScenarios":"Accessing a member of Listing that requires it to be a singleton (length == 1, e.g. the `single`-style accessor) when the listing has 0 or 2+ elements.","commonSituations":"Expecting exactly one dependency/mapping/file but the input config lists several (or none); type conversion of a Listing to a single value in typed schemas; a filter that matches multiple entries.","solutions":["Verify the list should contain exactly one element; fix the upstream data if it should.","Index explicitly (`items[0]` after length check) if multiple elements are acceptable, taking the intended one.","Add a length guard: `if (items.length != 1) ... else ...` and handle both branches.","Tighten filtering so only one element remains before the conversion."],"exampleFix":"// before\nmain = files.single // fails when files has 0 or >1 entries\n\n// after\nmain = if (files.length == 1) files.first else throw(\"expected exactly one file, got \\(files.length)\")","handlingStrategy":"validation","validationCode":"// enforce singleton before conversion\nif (items.length != 1) throw(\"expected exactly one element, got \\(items.length)\")","typeGuard":null,"tryCatchPattern":"try { x = items.single } catch (e) { if (e.message.contains('expectedSingleElementListing')) x = items.first /* or handle */ else throw e }","preventionTips":["Validate list cardinality at the boundary where data enters","Tighten filters so exactly one item matches","Prefer explicit indexing with a length check over implicit singleton access"],"tags":["pkl","listing","collection-length","stdlib"],"backgroundTag":"empty-result-set","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"}