{"record":{"id":"441012c43f6b475f","repo":"apple/pkl","slug":"commandoptionunexpecteddefaultvalue","errorCode":"commandOptionUnexpectedDefaultValue","errorMessage":"commandOptionUnexpectedDefaultValue","messagePattern":"commandOptionUnexpectedDefaultValue","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/runtime/CommandSpecParser.java","lineNumber":351,"sourceCode":"    var shortName = exportNullableString(flagAnnotation, Identifier.SHORT_NAME);\n    checkFlagNames(prop, name, shortName);\n\n    // assert type is integral\n    var typeInfo = resolveType(prop);\n    if (typeInfo.getFirst().getVmClass() != BaseModule.getIntClass() || typeInfo.getSecond()) {\n      throw exceptionBuilder()\n          .withSourceSection(prop.getHeaderSection())\n          .evalError(\n              \"commandFlagInvalidType\",\n              prop.getName(),\n              \"CountedFlag\",\n              typeInfo.getFirst().getSourceSection().getCharacters(),\n              \"Int\")\n          .build();\n    }\n\n    if (getDefaultValue(prop, true) != null) {\n      throw exceptionBuilder()\n          .withSourceSection(prop.getHeaderSection())\n          .evalError(\"commandOptionUnexpectedDefaultValue\", prop.getName(), \"Argument\")\n          .build();\n    }\n\n    return new CountedFlag(\n        name,\n        VmUtils.exportDocComment(prop.getDocComment()),\n        shortName,\n        (Boolean) VmUtils.readMember(flagAnnotation, Identifier.HIDE));\n  }\n\n  private Argument collectArgument(ClassProperty prop, VmTyped argAnnotation) {\n    var behavior = new OptionBehavior(argAnnotation, false).resolve(prop, true);\n    if (behavior.getDefaultValue() != null) {\n      throw exceptionBuilder()\n          .withSourceSection(prop.getHeaderSection())\n          .evalError(\"commandOptionUnexpectedDefaultValue\", prop.getName(), \"Argument\")","sourceCodeStart":333,"sourceCodeEnd":369,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/runtime/CommandSpecParser.java#L333-L369","documentation":"Thrown when a CountedFlag (or Argument) CLI property declares a default value, which is not allowed. Counted flags implicitly default to zero increments and arguments have no independent default, so any explicit `default:` on such a property is treated as a spec error at parse time.","triggerScenarios":"Writing `@CountedFlag { verbosity { default = 2 } }` or a similar default-value declaration on a property collected by collectCountedFlag (or collectArgument) while parsing the command spec class.","commonSituations":"Reusing an existing option property definition (which legally carries a default) and swapping the annotation to @CountedFlag; adding a `default` property in the annotation body out of habit from regular options.","solutions":["Remove the `default = ...` property from the @CountedFlag declaration","Model the default by adding the flag that many times at invocation instead, or handle zero-count in command logic","Use a regular @Option instead if a default value is truly required"],"exampleFix":"// before\n@CountedFlag verbosity: Int { default = 1 }\n\n// after\n@CountedFlag verbosity: Int","handlingStrategy":"validation","validationCode":"// check before registering the command spec\nfunction validateCountedFlags(props: Listing<ClassProperty>): Listing<String> {\n  props.filter((p) -> p.hasAnnotation(\"CountedFlag\") && \"default\" in p)\n       .map((p) -> p.name)\n}","typeGuard":null,"tryCatchPattern":"try {\n  CliCommand.parse(spec, args)\n} catch (EvaluationException e) {\n  if (e.getMessage().contains(\"commandOptionUnexpectedDefaultValue\")) {\n    // report the offending property from the message and fail spec load\n  }\n}","preventionTips":["Keep annotation bodies minimal for CountedFlag/Argument — only name/shortName/hide/multiple","Copy annotation bodies carefully when converting options to flags/arguments"],"tags":["pkl","cli","default-value","counted-flag"],"backgroundTag":"conflicting-config-options","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"}