'-outfilelist' flag applicable only when -pkgcfg used

Error message

'-outfilelist' flag applicable only when -pkgcfg used

What it means

Thrown by 'go tool cover' parseFlags when -outfilelist is set but -pkgcfg is NOT set. -outfilelist is only meaningful in the full-package instrumentation workflow (which requires -pkgcfg); using it in single-file mode is a user error.

Source

Thrown at src/cmd/cover/cover.go:195

				}
				var err error
				if outputfiles, err = readOutFileList(*outfilelist); err != nil {
					return err
				}
				covervarsoutfile = outputfiles[0]
				outputfiles = outputfiles[1:]
				numInputs := len(flag.Args())
				numOutputs := len(outputfiles)
				if numOutputs != numInputs {
					return fmt.Errorf("number of output files (%d) not equal to number of input files (%d)", numOutputs, numInputs)
				}
				if err := readPackageConfig(*pkgcfg); err != nil {
					return err
				}
				return nil
			} else {
				if *outfilelist != "" {
					return fmt.Errorf("'-outfilelist' flag applicable only when -pkgcfg used")
				}
			}
			if flag.NArg() == 1 {
				return nil
			}
		}
	} else if flag.NArg() == 0 {
		return nil
	}
	return fmt.Errorf("too many arguments")
}

func readOutFileList(path string) ([]string, error) {
	data, err := os.ReadFile(path)
	if err != nil {
		return nil, fmt.Errorf("error reading -outfilelist file %q: %v", path, err)
	}
	return strings.Split(strings.TrimSpace(string(data)), "\n"), nil

View on GitHub (pinned to b6b368adc5)

Solutions

Remove -outfilelist unless you are also using -pkgcfg
If instrumenting a package, add -pkgcfg pointing at a valid config file

Example fix

# before
go tool cover -mode=set -outfilelist=files.txt input.go
# after
go tool cover -mode=set input.go

Defensive patterns

Strategy: validation

Validate before calling

# Only allow -outfilelist with -pkgcfg
if [ -n "$OUTFILELIST" ] && [ -z "$PKGCFG" ]; then
  echo "-outfilelist requires -pkgcfg" >&2; exit 2
fi

Prevention

Keep -outfilelist and -pkgcfg paired in scripts
Strip both when downgrading to single-file mode

When it happens

Trigger: `go tool cover -mode=set -outfilelist=files.txt input.go` (no -pkgcfg).

Common situations: Copy-pasting flags from a package-instrumentation command into a single-file invocation. Stale build script that leaves -outfilelist set after removing -pkgcfg.

Related errors

AI-assisted analysis of golang/go@b6b368adc5 (2026-08-12). Data as JSON: /api/errors/85bd2d86eaa52fe3. Report an issue: GitHub.