{"record":{"id":"02123d64a67d7749","repo":"apple/pkl","slug":"missing-argument-module","errorCode":null,"errorMessage":"Missing argument \"module\".","messagePattern":"Missing argument \"module\"\\.","errorType":"console","errorClass":"MissingArgument","httpStatus":null,"severity":"error","filePath":"pkl-cli/src/main/kotlin/org/pkl/cli/commands/RunCommand.kt","lineNumber":68,"sourceCode":"\n  val module: URI? by\n    argument(\n        name = \"module\",\n        help = \"Root pkl:Command module to invoke.\",\n        completionCandidates = CompletionCandidates.Path,\n      )\n      .convert { BaseOptions.parseModuleName(it) }\n      .optional()\n\n  val args: List<String> by argument(name = \"args\").multiple()\n\n  private val projectOptions by ProjectOptions()\n\n  override fun run() {\n    // if no module is specified but --help is show help, otherwise error becuase module is missing\n    if (module == null)\n      if (showHelp) throw PrintHelpMessage(currentContext)\n      else throw MissingArgument(registeredArguments().find { it.name == \"module\" }!!)\n\n    val reservedFlagNames = mutableSetOf(\"help\")\n    val reservedFlagShortNames = mutableSetOf(\"h\")\n    registeredOptions().forEach { opt ->\n      (opt.names + opt.secondaryNames).forEach {\n        if (it.startsWith(\"--\")) reservedFlagNames.add(it.trimStart('-'))\n        else reservedFlagShortNames.add(it.trimStart('-'))\n      }\n    }\n    CliCommandRunner(\n        baseOptions.baseOptions(listOf(module!!), projectOptions),\n        reservedFlagNames,\n        reservedFlagShortNames,\n        if (showHelp) args + listOf(\"--help\") else args,\n      )\n      .run()\n  }\n}","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-cli/src/main/kotlin/org/pkl/cli/commands/RunCommand.kt#L50-L86","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass the module: `pkl run script.pkl` or a URI like `pkl run package://example.com/foo@1.0.0`","Guard wrapper scripts: fail fast if the module variable is empty","Check the working directory/project setup if you expected the module to be inferred (it is not inferred automatically)"],"exampleFix":"// before\npkl run\n// after\npkl run mypkg/Main.pkl","handlingStrategy":"validation","validationCode":"// guard the module argument before invoking pkl run\nMODULE=\"${1:?usage: pkl run <module.pkl>}\"\n[[ -e $MODULE || $MODULE == *\"://\"* ]] || { echo \"module not found: $MODULE\" >&2; exit 2; }","typeGuard":"function hasModuleArg(args: string[]): args is [string, ...string[]] {\n  return args.length > 0 && args[0].length > 0;\n}","tryCatchPattern":"try {\n  runCommand.run()\n} catch (e: MissingArgument) {\n  if (e.argument.name == \"module\") {\n    System.err.println(\"usage: pkl run <module.pkl>\");\n    exitProcess(2);\n  } else throw e;\n}","preventionTips":["Always supply a .pkl module path or URI to pkl run","Use ${VAR:?} shell expansions to fail on empty module variables","Add a smoke test that runs your standard CLI invocation in CI"],"tags":["cli","pkl","missing-argument","module"],"backgroundTag":"missing-required-argument","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"}