apple/pkl · error · VmException

expectedSingleElementListing

expectedSingleElementListing

Error message

expectedSingleElementListing

What it means

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.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/stdlib/base/ListingNodes.java:342

          });
      return builder.build();
    }
  }

  private static void checkNonEmpty(VmListing self, PklNode node) {
    if (self.isEmpty()) {
      CompilerDirectives.transferToInterpreter();
      throw new VmExceptionBuilder()
          .evalError("expectedNonEmptyListing")
          .withLocation(node)
          .build();
    }
  }

  private static void checkSingleton(VmListing self, PklNode node) {
    if (self.getLength() != 1) {
      CompilerDirectives.transferToInterpreter();
      throw new VmExceptionBuilder()
          .evalError("expectedSingleElementListing")
          .withLocation(node)
          .build();
    }
  }
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Verify the list should contain exactly one element; fix the upstream data if it should.
2. Index explicitly (`items[0]` after length check) if multiple elements are acceptable, taking the intended one.
3. Add a length guard: `if (items.length != 1) ... else ...` and handle both branches.
4. Tighten filtering so only one element remains before the conversion.

Example fix

// before
main = files.single // fails when files has 0 or >1 entries

// after
main = if (files.length == 1) files.first else throw("expected exactly one file, got \(files.length)")

// enforce singleton before conversion
if (items.length != 1) throw("expected exactly one element, got \(items.length)")

try { x = items.single } catch (e) { if (e.message.contains('expectedSingleElementListing')) x = items.first /* or handle */ else throw e }

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: EmptyResultError / "no results found": when an API or scraper succeeds but returns zero rows — this error's family across 9 libraries.

Related errors

• expectedNonEmptyListing
• cannotFindStdLibModule
• defaultMember/cannotFindMember
• cannotInstantiateExternalClass
• cannotDefineExternalMember

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