apple/pkl · error · MissingArgument

Missing argument "${argument}".

Error message

Missing argument "${argument}".

What it means

While converting positional argument values in a synthesized run command, a CommandSpec.Option.MissingOption from picocli is rethrown as MissingArgument(argument), producing "Missing argument \"<name>\".". It means a required positional argument (such as the module argument) was not provided.

Source

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

              option(names = opt.names, help = opt.helpText ?: "", hidden = opt.hidden)
                .int()
                .transformValues(0..0) { it.lastOrNull() ?: 1 }
                .transformAll { it.sum().toLong() }
            )
          is CommandSpec.Argument ->
            registerArgument(
              argument(
                  opt.name,
                  opt.helpText ?: "",
                  completionCandidates = opt.completionCandidates?.toClikt(),
                )
                .convert {
                  try {
                    opt.transformEach.apply(it, workingDirUri)
                  } catch (e: CommandSpec.Option.BadValue) {
                    fail(e.message!!)
                  } catch (_: CommandSpec.Option.MissingOption) {
                    throw MissingArgument(argument)
                  }
                }
                .transformAll(if (opt.repeated) -1 else 1, !opt.repeated) {
                  try {
                    opt.transformAll.apply(it, workingDirUri)
                  } catch (e: CommandSpec.Option.BadValue) {
                    fail(e.message!!)
                  } catch (_: CommandSpec.Option.MissingOption) {
                    throw MissingArgument(argument)
                  }
                }
            )
        }
      }
      spec.subcommands.forEach { subcommands(SynthesizedRunCommand(it, runner)) }
    }

    val workingDirUri: URI by lazy { runner.options.normalizedWorkingDir.toUri() }

View on GitHub (pinned to f3efcbfc9b)

Solutions

  1. Supply the required positional argument, e.g. `pkl run script.pkl`
  2. Check the command's `--help` to see required arguments
  3. Fix wrapper scripts that drop empty variables representing the argument

Example fix

// before
pkl run
// after
pkl run script.pkl
Defensive patterns

Strategy: validation

Validate before calling

// validate positional args before invoking the CLI
if (process.argv.length < 2) {
  console.error('Missing argument "module"');
  process.exit(2);
}

Try / catch

try {
  CliCommandRunner(args).run()
} catch (e: MissingArgument) {
  System.err.println("${e.argument} is required: pkl run <module.pkl>")
  System.exit(2)
}

Prevention

When it happens

Trigger: Invoking a synthesized command without its required positional argument; picocli raises MissingOption during the transformEach conversion of the argument and the runner maps it to MissingArgument.

Common situations: Running `pkl run` or a synthesized subcommand with no .pkl file argument; wrapping scripts that lose the argument due to shell quoting; automated tooling invoking the CLI with an empty module path.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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