apple/pkl · error

commandFlagInvalidType

commandFlagInvalidType

Error message

commandFlagInvalidType

What it means

collectBooleanFlag throws commandFlagInvalidType when a property annotated with @BooleanFlag (a flag that takes no value) is not declared with type Boolean. The offending property's declared type source text is included in the message so the mismatch is easy to spot.

Source

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

        behavior.getCompletionCandidates(),
        shortName,
        behavior.getMetavar(),
        hide,
        (behavior.getDefaultValue() == COMPLEX_DEFAULT_EXPRESSION
                || behavior.getDefaultValue() == null)
            ? null
            : behavior.getDefaultValue().toString());
  }

  private CommandSpec.BooleanFlag collectBooleanFlag(ClassProperty prop, VmTyped flagAnnotation) {
    var name = prop.getName().toString();
    var shortName = exportNullableString(flagAnnotation, Identifier.SHORT_NAME);
    checkFlagNames(prop, name, shortName);

    // assert type is Boolean
    var typeInfo = resolveType(prop);
    if (!(typeInfo.getFirst() instanceof TypeNode.BooleanTypeNode)) {
      throw exceptionBuilder()
          .withSourceSection(prop.getHeaderSection())
          .evalError(
              "commandFlagInvalidType",
              prop.getName(),
              "BooleanFlag",
              typeInfo.getFirst().getSourceSection().getCharacters(),
              "Boolean")
          .build();
    }

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

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Change the property type to Boolean, or
2. Use the appropriate flag annotation for the declared type (e.g. @Flag for value-taking flags, @CountedFlag for counters)
3. Remove the annotation if the property is not meant to be a CLI flag

Example fix

// before
@BooleanFlag
level: Int
// after
@CountedFlag
level: Int

const boolOnly = { BooleanFlag: true };
if (boolOnly[flag.annotation] && flag.declaredType !== "Boolean") {
  throw new Error(`@BooleanFlag requires Boolean, got ${flag.declaredType}`);
}

function isValidBooleanFlag(p) { return p.annotation !== "BooleanFlag" || p.type === "Boolean"; }

When it happens

Trigger: Annotating a property typed String, Int, Enum, etc. with @BooleanFlag; e.g. `@BooleanFlag level: Int`.

Common situations: Copy-pasting @BooleanFlag onto an option that takes a value; forgetting that value-taking flags need a different annotation (@Flag/@CountedFlag) and type; changing the property type after adding the annotation.

Understand the failure class

Background: "unknown output mode", "invalid value for flag", "expects true/false": fixing invalid flag value errors in CLI tools — this error's family across 24 libraries.

Related errors

• commandOptionsTypeNotClass
• +e.getMessage()
• commandSubcommandConflict
• commandOptionsTypeAbstractClass
• commandOptionBothFlagAndArgument

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