{"record":{"id":"cace2e3148e28e52","repo":"apple/pkl","slug":"commandflaginvalidtype","errorCode":"commandFlagInvalidType","errorMessage":"commandFlagInvalidType","messagePattern":"commandFlagInvalidType","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/runtime/CommandSpecParser.java","lineNumber":312,"sourceCode":"        behavior.getCompletionCandidates(),\n        shortName,\n        behavior.getMetavar(),\n        hide,\n        (behavior.getDefaultValue() == COMPLEX_DEFAULT_EXPRESSION\n                || behavior.getDefaultValue() == null)\n            ? null\n            : behavior.getDefaultValue().toString());\n  }\n\n  private CommandSpec.BooleanFlag collectBooleanFlag(ClassProperty prop, VmTyped flagAnnotation) {\n    var name = prop.getName().toString();\n    var shortName = exportNullableString(flagAnnotation, Identifier.SHORT_NAME);\n    checkFlagNames(prop, name, shortName);\n\n    // assert type is Boolean\n    var typeInfo = resolveType(prop);\n    if (!(typeInfo.getFirst() instanceof TypeNode.BooleanTypeNode)) {\n      throw exceptionBuilder()\n          .withSourceSection(prop.getHeaderSection())\n          .evalError(\n              \"commandFlagInvalidType\",\n              prop.getName(),\n              \"BooleanFlag\",\n              typeInfo.getFirst().getSourceSection().getCharacters(),\n              \"Boolean\")\n          .build();\n    }\n\n    return new BooleanFlag(\n        name,\n        VmUtils.exportDocComment(prop.getDocComment()),\n        shortName,\n        (Boolean) VmUtils.readMember(flagAnnotation, Identifier.HIDE),\n        (Boolean) getDefaultValue(prop, false));\n  }\n","sourceCodeStart":294,"sourceCodeEnd":330,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/runtime/CommandSpecParser.java#L294-L330","documentation":"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.","triggerScenarios":"Annotating a property typed String, Int, Enum, etc. with @BooleanFlag; e.g. `@BooleanFlag level: Int`.","commonSituations":"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.","solutions":["Change the property type to Boolean, or","Use the appropriate flag annotation for the declared type (e.g. @Flag for value-taking flags, @CountedFlag for counters)","Remove the annotation if the property is not meant to be a CLI flag"],"exampleFix":"// before\n@BooleanFlag\nlevel: Int\n// after\n@CountedFlag\nlevel: Int","handlingStrategy":"type-guard","validationCode":"const boolOnly = { BooleanFlag: true };\nif (boolOnly[flag.annotation] && flag.declaredType !== \"Boolean\") {\n  throw new Error(`@BooleanFlag requires Boolean, got ${flag.declaredType}`);\n}","typeGuard":"function isValidBooleanFlag(p) { return p.annotation !== \"BooleanFlag\" || p.type === \"Boolean\"; }","tryCatchPattern":null,"preventionTips":["Match annotation to type: @BooleanFlag -> Boolean, @CountedFlag -> Int, @Flag -> value types","Re-check annotations after changing property types","Keep flags Boolean unless a value-taking annotation is intended"],"tags":["pkl","cli","command-spec","types"],"backgroundTag":"invalid-flag-value","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}