txthinking/brook · error

--pid must be with absolute path

Error message

--pid must be with absolute path

What it means

The brook CLI's app.Before hook validates global flags before running any subcommand. If --pid is provided as a relative path, it refuses to run because the PID file location must be unambiguous regardless of working directory. The error aborts command execution.

Source

Thrown at cli/brook/main.go:169

		&cli.StringSliceFlag{
			Name:  "blockGeoIP",
			Usage: "Block IP by Geo country code, such as US. Works with server/wsserver/wssserver/quicserver",
		},
		&cli.Int64Flag{
			Name:  "blockListUpdateInterval",
			Usage: "Update list --blockDomainList,--blockCIDR4List,--blockCIDR6List interval, second. default 0, only read one time on start",
		},
		&cli.StringFlag{
			Name:  "pid",
			Usage: "A file path used to store pid. Send SIGUSR1 to me to reset the --serverLog file on unix system",
		},
	}
	app.Before = func(c *cli.Context) error {
		brook.ClientHKDFInfo = []byte(c.String("clientHKDFInfo"))
		brook.ServerHKDFInfo = []byte(c.String("serverHKDFInfo"))
		if c.String("pid") != "" {
			if !filepath.IsAbs(c.String("pid")) {
				return errors.New("--pid must be with absolute path")
			}
			if err := os.WriteFile(c.String("pid"), []byte(strconv.Itoa(os.Getpid())), 0744); err != nil {
				return err
			}
		}
		if c.String("pprof") != "" {
			p, err := pprof.NewPprof(c.String("pprof"))
			if err != nil {
				return err
			}
			g.Add(&runnergroup.Runner{
				Start: func() error {
					return p.ListenAndServe()
				},
				Stop: func() error {
					return p.Shutdown()
				},
			})

View on GitHub (pinned to 5cd13ef3b1)

Solutions

1. Pass an absolute path: --pid /var/run/brook.pid
2. Prefix the value with $PWD in shell: --pid "$PWD/brook.pid"
3. Fix the service/unit file to use an absolute PIDFile path

Example fix

// before
brook server -l :9999 --pid brook.pid
// after
brook server -l :9999 --pid /var/run/brook.pid

if pidPath != "" && !filepath.IsAbs(pidPath) {
	return fmt.Errorf("--pid must be absolute, got %q", pidPath)
}

When it happens

Trigger: Running any brook subcommand with e.g. --pid brook.pid or --pid ./run/brook.pid — anything filepath.IsAbs returns false for.

Common situations: Copy-pasting example commands with relative paths; systemd/docker setups where CWD differs from what the operator assumed; scripts that cd around before writing the PID file.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

• --log must be with absolute path
• --blockDomainList must be with absolute path
• --blockCIDR4List must be with absolute path
• --blockCIDR6List must be with absolute path
• --cert must be with absolute path

AI-assisted analysis of txthinking/brook@5cd13ef3b1 (2026-09-06). Data as JSON: /api/errors/ca8124b6966fca45. Report an issue: GitHub.