What causes "Error: missing option --{0}" in apple/pkl?

Add the required option to the command line, e.g. `pkl ... -- `

apple/pkl · error · MissingOption

Error: missing option --{0}

Error message

Error: missing option --{0}

What it means

The CLI argument-parsing bridge in CliCommandRunner translates picocli's internal missing-option signal into a typed MissingOption error formatted as "Error: missing option --{0}". It is thrown while converting values of a synthesized (generated) run command when a required option was not supplied on the command line.

Source

Thrown at pkl-cli/src/main/kotlin/org/pkl/cli/CliCommandRunner.kt:167

    init {
      spec.options.forEach { opt ->
        when (opt) {
          is CommandSpec.Flag ->
            registerOption(
              option(
                  names = opt.names,
                  help = opt.helpText ?: "",
                  metavar = opt.metavar,
                  hidden = opt.hidden,
                  completionCandidates = opt.completionCandidates?.toClikt(),
                )
                .convert {
                  try {
                    opt.transformEach.apply(it, workingDirUri)
                  } catch (e: CommandSpec.Option.BadValue) {
                    fail(e.message!!)
                  } catch (_: CommandSpec.Option.MissingOption) {
                    throw MissingOption(option)
                  }
                }
                .transformAll(opt.defaultValue, opt.showAsRequired) {
                  try {
                    opt.transformAll.apply(it, workingDirUri)
                  } catch (e: CommandSpec.Option.BadValue) {
                    fail(e.message!!)
                  } catch (_: CommandSpec.Option.MissingOption) {
                    throw MissingOption(option)
                  }
                }
            )
          is CommandSpec.BooleanFlag ->
            registerOption(
              if (opt.defaultValue != null)
                option(names = opt.names, help = opt.helpText ?: "", hidden = opt.hidden)
                  .flag("--no-${opt.name}", default = opt.defaultValue!!)
              else

View on GitHub (pinned to f3efcbfc9b)

Solutions

Add the required option to the command line, e.g. `pkl ... --<option> <value>`
Run the command with `--help` to list required options
Check project/ProjectOptions configuration to see why the option is marked required

Example fix

// before
pkl eval script.pkl
// after
pkl eval script.pkl --required-option value

Defensive patterns

Strategy: try-catch

Validate before calling

// shell check before invoking
required_opts=(--project)
for o in "${required_opts[@]}"; do
  [[ " $* " == *" $o "* ]] || { echo "missing option $o" >&2; exit 2; }
done

Try / catch

try {
  cli.run(args)
} catch (e: CliException) {
  if (e is MissingOption) System.err.println("Provide ${e.optionName}, see --help")
  else throw e
}

Prevention

Always pass required flags explicitly in scripts, never rely on defaults
Use `--help` to audit which options are showAsRequired
Avoid unquoted empty shell variables for option values

When it happens

Trigger: Invoking a generated/synthesized run subcommand (e.g. via `pkl eval` command synthesis) while omitting a required option like `--project` or another option with showAsRequired=true; picocli raises CommandSpec.Option.MissingOption during transformAll conversion.

Common situations: Running `pkl eval script.pkl` where the project requires a mandatory CLI option; CI pipelines where the required flag was dropped from the command template; version upgrades that turned an option required.

Understand the failure class

Background: "Must pass :limit option" / "Missing required option" — required option errors explained — this error's family across 41 libraries.

Related errors

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