{"record":{"id":"bb2d9c4ab3ff43d1","repo":"apple/pkl","slug":"commandoptionunsupportedtype","errorCode":"commandOptionUnsupportedType","errorMessage":"commandOptionUnsupportedType","messagePattern":"commandOptionUnsupportedType","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/runtime/CommandSpecParser.java","lineNumber":597,"sourceCode":"                    var builder = VmMap.builder();\n                    values.forEach(\n                        (entry) ->\n                            builder.add(((VmPair) entry).getFirst(), ((VmPair) entry).getSecond()));\n                    return builder.build();\n                  };\n      } else if (typeNode instanceof TypeNode.PairTypeNode pairTypeNode) {\n        handleEntry(pairTypeNode.getFirstTypeNode(), pairTypeNode.getSecondTypeNode(), prop);\n        if (all == null) all = this::allChooseLast;\n        if (multiple == null) multiple = false;\n      } else if (typeNode instanceof TypeNode.FinalClassTypeNode finalClassTypeNode\n          && (finalClassTypeNode.getVmClass() == BaseModule.getListingClass()\n              || finalClassTypeNode.getVmClass() == BaseModule.getMappingClass()\n              || finalClassTypeNode.getVmClass() == BaseModule.getListClass()\n              || finalClassTypeNode.getVmClass() == BaseModule.getSetClass()\n              || finalClassTypeNode.getVmClass() == BaseModule.getMapClass()\n              || finalClassTypeNode.getVmClass() == BaseModule.getPairClass())) {\n        // if a supported type is provided without type arguments\n        throw exceptionBuilder()\n            .withSourceSection(prop.getHeaderSection())\n            .evalError(\n                \"commandOptionUnsupportedType\",\n                prop.getName(),\n                \"\",\n                typeNode.getSourceSection().getCharacters())\n            .withHint(\n                finalClassTypeNode.getVmClass().getSimpleName()\n                    + \" options must provide \"\n                    + switch (finalClassTypeNode.getVmClass().getTypeParameterCount()) {\n                      case 1 -> \"one type argument.\";\n                      case 2 -> \"two type arguments.\";\n                      default -> throw PklBugException.unreachableCode();\n                    })\n            .build();\n      } else if (each == null && all == null) {\n        // if another type and no transform functions are provided, that's an error\n        throw exceptionBuilder()","sourceCodeStart":579,"sourceCodeEnd":615,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/runtime/CommandSpecParser.java#L579-L615","documentation":"Thrown when an option's declared type is a supported generic collection (Listing, Mapping, List, Set, Map, or Pair) given WITHOUT its required type arguments. The framework needs element/key/value types to know how to convert each CLI token, so bare `List<Int>` is fine but bare `List` (or `Listing`) is rejected, with a hint about how many type arguments are needed.","triggerScenarios":"Declaring `@Option include: List` or `@Option headers: Mapping` — a FinalClassTypeNode for Listing/Mapping/List/Set/Map/Pair with no type arguments reaches OptionBehavior.resolve and fails the first commandOptionUnsupportedType branch.","commonSituations":"Using raw collection types in Pkl property declarations; older Pkl code where bare Listing was common; copy-pasted specs stripped of type args.","solutions":["Add the type arguments, e.g. `List<String>` or `Mapping<String, Int>`","For Listing/Mapping, parameterize them: `Listing<String>`, `Mapping<String, String>`","Use Pair<A, B> with both type arguments for pair-typed options"],"exampleFix":"// before\n@Option include: List\n\n// after\n@Option include: List<String>","handlingStrategy":"validation","validationCode":"// static check: collection-typed options must be parameterized\nfunction checkRawCollections(props: Listing<ClassProperty>): Listing<String> {\n  props.filter((p) -> p.type != null && p.type.isRawCollection())\n       .map((p) -> p.name)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never declare bare List/Set/Map/Listing/Mapping/Pair types for options — always add type arguments","Remember arity: 1 arg for List/Set/Listing, 2 for Map/Mapping/Pair","Run spec parsing in CI so raw collection types fail at build time"],"tags":["pkl","cli","type-arguments","unsupported-type"],"backgroundTag":"unsupported-config-value","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}