apple/pkl · error · MissingArgument

Missing argument "module".

Error message

Missing argument "module".

What it means

RunCommand.run() requires a module positional argument. When module == null and showHelp is false, it throws MissingArgument(registeredArguments().find { it.name == "module" }!!), producing "Missing argument \"module\".". This tells the user that `pkl run`/eval-target must point at a Pkl module.

Source

Thrown at pkl-cli/src/main/kotlin/org/pkl/cli/commands/RunCommand.kt:68

  val module: URI? by
    argument(
        name = "module",
        help = "Root pkl:Command module to invoke.",
        completionCandidates = CompletionCandidates.Path,
      )
      .convert { BaseOptions.parseModuleName(it) }
      .optional()

  val args: List<String> by argument(name = "args").multiple()

  private val projectOptions by ProjectOptions()

  override fun run() {
    // if no module is specified but --help is show help, otherwise error becuase module is missing
    if (module == null)
      if (showHelp) throw PrintHelpMessage(currentContext)
      else throw MissingArgument(registeredArguments().find { it.name == "module" }!!)

    val reservedFlagNames = mutableSetOf("help")
    val reservedFlagShortNames = mutableSetOf("h")
    registeredOptions().forEach { opt ->
      (opt.names + opt.secondaryNames).forEach {
        if (it.startsWith("--")) reservedFlagNames.add(it.trimStart('-'))
        else reservedFlagShortNames.add(it.trimStart('-'))
      }
    }
    CliCommandRunner(
        baseOptions.baseOptions(listOf(module!!), projectOptions),
        reservedFlagNames,
        reservedFlagShortNames,
        if (showHelp) args + listOf("--help") else args,
      )
      .run()
  }
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

  1. Pass the module: `pkl run script.pkl` or a URI like `pkl run package://example.com/foo@1.0.0`
  2. Guard wrapper scripts: fail fast if the module variable is empty
  3. Check the working directory/project setup if you expected the module to be inferred (it is not inferred automatically)

Example fix

// before
pkl run
// after
pkl run mypkg/Main.pkl
Defensive patterns

Strategy: validation

Validate before calling

// guard the module argument before invoking pkl run
MODULE="${1:?usage: pkl run <module.pkl>}"
[[ -e $MODULE || $MODULE == *"://"* ]] || { echo "module not found: $MODULE" >&2; exit 2; }

Type guard

function hasModuleArg(args: string[]): args is [string, ...string[]] {
  return args.length > 0 && args[0].length > 0;
}

Try / catch

try {
  runCommand.run()
} catch (e: MissingArgument) {
  if (e.argument.name == "module") {
    System.err.println("usage: pkl run <module.pkl>");
    exitProcess(2);
  } else throw e;
}

Prevention

When it happens

Trigger: Executing `pkl run` (or a run-synthesized command) without a .pkl file/module path and without the help flag; module remains null after picocli parsing.

Common situations: Forgetting the script path (e.g. `pkl run` alone); shell variable holding the module path is empty; automation calling the CLI with zero args after a config change.

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/02123d64a67d7749. Report an issue: GitHub.