{"record":{"id":"fe75110214e67140","repo":"golang/go","slug":"c-flag-must-be-first-flag-on-command-line","errorCode":null,"errorMessage":"-C flag must be first flag on command line","messagePattern":"-C flag must be first flag on command line","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/cmd/go/internal/base/flag.go","lineNumber":84,"sourceCode":"}\n\n// AddModFlag adds the -mod build flag to the flag set.\nfunc AddModFlag(flags *flag.FlagSet) {\n\tflags.Var(explicitStringFlag{value: &cfg.BuildMod, explicit: &cfg.BuildModExplicit}, \"mod\", \"module download `mode` to use: readonly, vendor, mod\")\n}\n\n// AddModCommonFlags adds the module-related flags common to build commands\n// and 'go mod' subcommands.\nfunc AddModCommonFlags(flags *flag.FlagSet) {\n\tflags.BoolVar(&cfg.ModCacheRW, \"modcacherw\", false, \"leave newly-created directories in the module cache read-write instead of making them read-only\")\n\tflags.StringVar(&cfg.ModFile, \"modfile\", \"\", \"read (and possibly write) an alternate go.mod `file` instead of the one in the module root directory\")\n\tflags.StringVar(&fsys.OverlayFile, \"overlay\", \"\", \"read a JSON config `file` that provides an overlay for build operations\")\n}\n\nfunc ChdirFlag(s string) error {\n\t// main handles -C by removing it from the command line.\n\t// If we see one during flag parsing, that's an error.\n\treturn fmt.Errorf(\"-C flag must be first flag on command line\")\n}\n","sourceCodeStart":66,"sourceCodeEnd":86,"githubUrl":"https://github.com/golang/go/blob/b6b368adc57c96c3151d224d172029f233ead2c3/src/cmd/go/internal/base/flag.go#L66-L86","documentation":"Returned by ChdirFlag, which is registered on subcommand flag sets by AddChdirFlag purely so usage/help is consistent. The global `-C dir` must appear before the subcommand; main.go strips it before subcommand parsing. ChdirFlag unconditionally returns this error, so any `-C` that reaches subcommand flag parsing is in the wrong position and is rejected.","triggerScenarios":"Running the go command with `-C` after the subcommand or anywhere other than the first global position, e.g. `go build -C dir ./...` or `go test ./... -C dir`.","commonSituations":"Assuming `-C` behaves like other build flags and works post-subcommand; copying `-C` into a script/CI command in the wrong position; muscle memory from tools that accept chdir flags anywhere.","solutions":["Place `-C dir` immediately after `go` and before the subcommand: `go -C dir build ./...`.","Alternatively `cd` into the target directory before running the go command.","Do not pass `-C` to subcommands; it is a global flag only."],"exampleFix":"// before\ngo build -C ../myproj ./...\n// after\ngo -C ../myproj build ./...","handlingStrategy":"validation","validationCode":"// Enforce that -C, if present, is the first global flag.\nargs := os.Args[1:]\nfor i, a := range args {\n    if a == \"-C\" || strings.HasPrefix(a, \"-C=\") {\n        if i != 0 && !isGlobalPosition(args, i) {\n            return errors.New(\"-C flag must be first flag on command line; use: go -C <dir> <subcommand>\")\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always place `-C dir` immediately after `go`, before the subcommand.","Or `cd` into the directory before running go.","Never pass `-C` to a subcommand."],"tags":["go-toolchain","flags","cli","chdir","usage","command-line"],"backgroundTag":null,"analyzedSha":"b6b368adc57c96c3151d224d172029f233ead2c3","analyzedAt":"2026-08-12T00:22:02.250Z","schemaVersion":2},"datasetVersion":"2026-08-12T12:31:55.035Z"}