dagger/dagger · error

unknown flag: "--help"

Error message

unknown flag: "--help"

What it means

checkErrHelp converts pflag's help-requested sentinel into `unknown flag: "--help"` when `--help` appears in the argument list before `--`. Module function flag sets don't define `--help`, so requesting help triggers this explicit error rather than pflag's default.

Source

Thrown at internal/cmd/dagger/shell_exec.go:664

}

// checkErrHelp circumvents pflag's special cases for -h and --help
//
// This returns the same error as any other unknown flag.
func checkErrHelp(err error, args []string) error {
	if !errors.Is(err, pflag.ErrHelp) {
		return err
	}
	// Avoid considering flags from a with-exec for example, although if this
	// error is raised it's surely defined before `--`.
	if i := slices.Index(args, "--"); i > 0 {
		args = args[:i]
	}
	// Shorthand flags are parsed first
	if slices.Contains(args, "-h") {
		return errors.New(`unknown shorthand flag: "-h"`)
	}
	return errors.New(`unknown flag: "--help"`)
}

// parseArgumentValues returns a map of argument names and their parsed values
func (h *shellCallHandler) parseArgumentValues(
	ctx context.Context,
	md *moduleDef,
	fn *modFunction,
	args []string,
) (rargs map[string]any, rerr error) {
	values, newArgs, err := h.shellPreprocessArgs(ctx, fn, args)
	if err != nil {
		return nil, errors.Join(err, fmt.Errorf("usage: %s", h.FunctionFullUseLine(md, fn)))
	}

	// Flag processing can be a source of bugs so it's very useful to be
	// able to debug this step but excessive on default verbosity.
	if debugFlag && verbose > 3 && !slices.Equal(args, newArgs) {
		dbgArgs := []any{

View on GitHub (pinned to 82ba2681db)

Solutions

1. Move `--help` before the function name to get dagger-level help: `dagger call --help`.
2. If `--help` is intended for the command the function executes, place it after `--`: `dagger call my-fn -- --help`.
3. Consult `dagger functions` to list available module functions and their usage.

Example fix

// before
dagger call my-fn --help
// after
dagger call --help           # or: dagger call my-fn -- --help to pass literally

# strip --help from function args in wrapper scripts
filtered=(); for a in "$@"; do [[ "$a" == --help ]] && { show_help=1; continue; }; filtered+=("$a"); done

out=$(dagger call my-fn "$@" 2>&1) || {
  [[ "$out" == *'unknown flag: "--help"'* ]] && dagger call --help && exit 0
  echo "$out" >&2; exit 1
}

When it happens

Trigger: Running `dagger call my-fn --help` where the pre-parser sees `--help` before `--` and there is no `-h` present (the -h branch is checked first); occurs in shellPreprocessArgs and parseArgumentValues flag parsing.

Common situations: Users expect `--help` on every subcommand; wrapper scripts inject `--help`; the flag was placed after other args, so it's treated as a function flag rather than a top-level dagger flag.

Related errors

• unknown shorthand flag: "-h"
• invalid value %s
• invalid label format (must be name:value)
• module ref cannot be empty
• module source ref cannot be empty

AI-assisted analysis of dagger/dagger@82ba2681db (2026-09-05). Data as JSON: /api/errors/a3d9f9f8bed10931. Report an issue: GitHub.