apple/pkl · error

commandOptionUnexpectedDefaultValue

commandOptionUnexpectedDefaultValue

Error message

commandOptionUnexpectedDefaultValue

What it means

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.

Solutions

  1. Remove the `default = ...` property from the @CountedFlag declaration
  2. Model the default by adding the flag that many times at invocation instead, or handle zero-count in command logic
  3. Use a regular @Option instead if a default value is truly required

Example fix

// before
@CountedFlag verbosity: Int { default = 1 }

// after
@CountedFlag verbosity: Int
Defensive patterns

Strategy: validation

Validate before calling

// check before registering the command spec
function validateCountedFlags(props: Listing<ClassProperty>): Listing<String> {
  props.filter((p) -> p.hasAnnotation("CountedFlag") && "default" in p)
       .map((p) -> p.name)
}

Try / catch

try {
  CliCommand.parse(spec, args)
} catch (EvaluationException e) {
  if (e.getMessage().contains("commandOptionUnexpectedDefaultValue")) {
    // report the offending property from the message and fail spec load
  }
}

Prevention

When it happens

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

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

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

Thrown at pkl-core/src/main/java/org/pkl/core/runtime/CommandSpecParser.java:351

    var shortName = exportNullableString(flagAnnotation, Identifier.SHORT_NAME);
    checkFlagNames(prop, name, shortName);

    // assert type is integral
    var typeInfo = resolveType(prop);
    if (typeInfo.getFirst().getVmClass() != BaseModule.getIntClass() || typeInfo.getSecond()) {
      throw exceptionBuilder()
          .withSourceSection(prop.getHeaderSection())
          .evalError(
              "commandFlagInvalidType",
              prop.getName(),
              "CountedFlag",
              typeInfo.getFirst().getSourceSection().getCharacters(),
              "Int")
          .build();
    }

    if (getDefaultValue(prop, true) != null) {
      throw exceptionBuilder()
          .withSourceSection(prop.getHeaderSection())
          .evalError("commandOptionUnexpectedDefaultValue", prop.getName(), "Argument")
          .build();
    }

    return new CountedFlag(
        name,
        VmUtils.exportDocComment(prop.getDocComment()),
        shortName,
        (Boolean) VmUtils.readMember(flagAnnotation, Identifier.HIDE));
  }

  private Argument collectArgument(ClassProperty prop, VmTyped argAnnotation) {
    var behavior = new OptionBehavior(argAnnotation, false).resolve(prop, true);
    if (behavior.getDefaultValue() != null) {
      throw exceptionBuilder()
          .withSourceSection(prop.getHeaderSection())
          .evalError("commandOptionUnexpectedDefaultValue", prop.getName(), "Argument")

View on GitHub (pinned to f3efcbfc9b)