{"record":{"id":"a3d9f9f8bed10931","repo":"dagger/dagger","slug":"unknown-flag-help","errorCode":null,"errorMessage":"unknown flag: \"--help\"","messagePattern":"unknown flag: \"--help\"","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/cmd/dagger/shell_exec.go","lineNumber":664,"sourceCode":"}\n\n// checkErrHelp circumvents pflag's special cases for -h and --help\n//\n// This returns the same error as any other unknown flag.\nfunc checkErrHelp(err error, args []string) error {\n\tif !errors.Is(err, pflag.ErrHelp) {\n\t\treturn err\n\t}\n\t// Avoid considering flags from a with-exec for example, although if this\n\t// error is raised it's surely defined before `--`.\n\tif i := slices.Index(args, \"--\"); i > 0 {\n\t\targs = args[:i]\n\t}\n\t// Shorthand flags are parsed first\n\tif slices.Contains(args, \"-h\") {\n\t\treturn errors.New(`unknown shorthand flag: \"-h\"`)\n\t}\n\treturn errors.New(`unknown flag: \"--help\"`)\n}\n\n// parseArgumentValues returns a map of argument names and their parsed values\nfunc (h *shellCallHandler) parseArgumentValues(\n\tctx context.Context,\n\tmd *moduleDef,\n\tfn *modFunction,\n\targs []string,\n) (rargs map[string]any, rerr error) {\n\tvalues, newArgs, err := h.shellPreprocessArgs(ctx, fn, args)\n\tif err != nil {\n\t\treturn nil, errors.Join(err, fmt.Errorf(\"usage: %s\", h.FunctionFullUseLine(md, fn)))\n\t}\n\n\t// Flag processing can be a source of bugs so it's very useful to be\n\t// able to debug this step but excessive on default verbosity.\n\tif debugFlag && verbose > 3 && !slices.Equal(args, newArgs) {\n\t\tdbgArgs := []any{","sourceCodeStart":646,"sourceCodeEnd":682,"githubUrl":"https://github.com/dagger/dagger/blob/82ba2681dbe30d3547a1dc50ea495900ab5b6047/internal/cmd/dagger/shell_exec.go#L646-L682","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Move `--help` before the function name to get dagger-level help: `dagger call --help`.","If `--help` is intended for the command the function executes, place it after `--`: `dagger call my-fn -- --help`.","Consult `dagger functions` to list available module functions and their usage."],"exampleFix":"// before\ndagger call my-fn --help\n// after\ndagger call --help           # or: dagger call my-fn -- --help to pass literally","handlingStrategy":"validation","validationCode":"# strip --help from function args in wrapper scripts\nfiltered=(); for a in \"$@\"; do [[ \"$a\" == --help ]] && { show_help=1; continue; }; filtered+=(\"$a\"); done","typeGuard":null,"tryCatchPattern":"out=$(dagger call my-fn \"$@\" 2>&1) || {\n  [[ \"$out\" == *'unknown flag: \"--help\"'* ]] && dagger call --help && exit 0\n  echo \"$out\" >&2; exit 1\n}","preventionTips":["Request help at the dagger level, not on the function invocation","Place literal --help after `--` when it belongs to the executed command","Update wrapper scripts that blindly forward --help"],"tags":["cli","flags","help","shell"],"backgroundTag":"unknown-flag","analyzedSha":"82ba2681dbe30d3547a1dc50ea495900ab5b6047","analyzedAt":"2026-09-05T07:21:37.930Z","contentChangedAt":"2026-09-05T07:21:37.930Z","schemaVersion":2},"datasetVersion":"2026-09-12T12:17:11.808Z"}