apple/pkl · error

commandFlagNameCollision

commandFlagNameCollision

Error message

commandFlagNameCollision

What it means

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.

Source

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

            flag = collectBooleanFlag(prop, flagAnnotation);
          } else if (flagAnnotation.getVmClass() == CommandModule.getCountedFlagClass()) {
            flag = collectCountedFlag(prop, flagAnnotation);
          } else {
            throw PklBugException.unreachableCode();
          }
          opts.put(flag.name(), flag);
        }
      }
      clazz = clazz.getSuperclass();
    }

    return opts.getValues();
  }

  private void checkFlagNames(ClassProperty prop, String name, @Nullable String shortName) {
    for (var reserved : reservedFlagNames) {
      if (reserved.equals(name)) {
        throw exceptionBuilder()
            .withSourceSection(prop.getHeaderSection())
            .evalError("commandFlagNameCollision", prop.getName(), "name", "")
            .build();
      }
    }
    for (var reserved : reservedFlagShortNames) {
      if (reserved.equals(shortName)) {
        throw exceptionBuilder()
            .withSourceSection(prop.getHeaderSection())
            .evalError(
                "commandFlagNameCollision", prop.getName(), "short name", "`" + shortName + "` ")
            .build();
      }
    }
  }

  private CommandSpec.Flag collectFlag(ClassProperty prop, @Nullable VmTyped flagAnnotation) {
    var name = prop.getName().toString();

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Rename the property or set an explicit `name` on the flag annotation that avoids the reserved word
2. Prefix the flag (e.g. `showHelp` or `helpOutput`) to dodge the collision
3. Check the framework's reserved flag name list before naming flags

Example fix

// before
@BooleanFlag
help: Boolean
// after
@BooleanFlag { name = "printHelp" }
help: Boolean

const RESERVED = ["help", "version"];
if (RESERVED.includes(flagName)) throw new Error(`flag name '${flagName}' is reserved`);

When it happens

Trigger: Declaring a flag whose computed or explicit `name` matches an entry in reservedFlagNames within an options class.

Common situations: Naming a flag `help`, `version`, or another reserved word; relying on a property name that happens to collide with a reserved flag.

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

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

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