{"record":{"id":"337b96524a85ec35","repo":"apple/pkl","slug":"commandflagnamecollision","errorCode":"commandFlagNameCollision","errorMessage":"commandFlagNameCollision","messagePattern":"commandFlagNameCollision","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/runtime/CommandSpecParser.java","lineNumber":260,"sourceCode":"            flag = collectBooleanFlag(prop, flagAnnotation);\n          } else if (flagAnnotation.getVmClass() == CommandModule.getCountedFlagClass()) {\n            flag = collectCountedFlag(prop, flagAnnotation);\n          } else {\n            throw PklBugException.unreachableCode();\n          }\n          opts.put(flag.name(), flag);\n        }\n      }\n      clazz = clazz.getSuperclass();\n    }\n\n    return opts.getValues();\n  }\n\n  private void checkFlagNames(ClassProperty prop, String name, @Nullable String shortName) {\n    for (var reserved : reservedFlagNames) {\n      if (reserved.equals(name)) {\n        throw exceptionBuilder()\n            .withSourceSection(prop.getHeaderSection())\n            .evalError(\"commandFlagNameCollision\", prop.getName(), \"name\", \"\")\n            .build();\n      }\n    }\n    for (var reserved : reservedFlagShortNames) {\n      if (reserved.equals(shortName)) {\n        throw exceptionBuilder()\n            .withSourceSection(prop.getHeaderSection())\n            .evalError(\n                \"commandFlagNameCollision\", prop.getName(), \"short name\", \"`\" + shortName + \"` \")\n            .build();\n      }\n    }\n  }\n\n  private CommandSpec.Flag collectFlag(ClassProperty prop, @Nullable VmTyped flagAnnotation) {\n    var name = prop.getName().toString();","sourceCodeStart":242,"sourceCodeEnd":278,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/runtime/CommandSpecParser.java#L242-L278","documentation":"checkFlagNames throws commandFlagNameCollision when a flag's long name equals a reserved flag name used by the Pkl CLI framework itself (e.g. 'help'/'version' style reserved names). The property name is reported with the 'name' kind; reserving names prevents ambiguity with built-in flags.","triggerScenarios":"Declaring a flag whose computed or explicit `name` matches an entry in reservedFlagNames within an options class.","commonSituations":"Naming a flag `help`, `version`, or another reserved word; relying on a property name that happens to collide with a reserved flag.","solutions":["Rename the property or set an explicit `name` on the flag annotation that avoids the reserved word","Prefix the flag (e.g. `showHelp` or `helpOutput`) to dodge the collision","Check the framework's reserved flag name list before naming flags"],"exampleFix":"// before\n@BooleanFlag\nhelp: Boolean\n// after\n@BooleanFlag { name = \"printHelp\" }\nhelp: Boolean","handlingStrategy":"validation","validationCode":"const RESERVED = [\"help\", \"version\"];\nif (RESERVED.includes(flagName)) throw new Error(`flag name '${flagName}' is reserved`);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep the reserved-flag list handy when naming flags","Prefer descriptive non-reserved names for flags","Use explicit `name` in the annotation when the property name collides"],"tags":["pkl","cli","command-spec","naming"],"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"}