What causes "parsing port: %w" in AdguardTeam/AdGuardHome?

Pass a plain decimal integer between 1 and 65535: -p 3000

parsing port: %w

Error message

parsing port: %w

What it means

The -p/--port command-line flag value could not be parsed as an unsigned 16-bit integer. strconv.ParseUint(v, 10, 16) fails on non-numeric input, negative numbers, or values above 65535.

Source

Thrown at internal/home/options.go:175

	},
	updateNoValue: nil,
	effect:        nil,
	serialize: func(o options) (val string, ok bool) {
		if !o.bindHost.IsValid() {
			return "", false
		}

		return o.bindHost.String(), true
	},
	description: "Deprecated. Host address to bind HTTP server on. Use --web-addr. " +
		"The short -h will work as --help in the future.",
	longName:  "host",
	shortName: "h",
}, {
	updateWithValue: func(o options, v string) (options, error) {
		p, err := strconv.ParseUint(v, 10, 16)
		if err != nil {
			err = fmt.Errorf("parsing port: %w", err)
		} else {
			o.bindPort = uint16(p)
		}

		return o, err
	},
	updateNoValue: nil,
	effect:        nil,
	serialize: func(o options) (val string, ok bool) {
		if o.bindPort == 0 {
			return "", false
		}

		return strconv.Itoa(int(o.bindPort)), true
	},
	description: "Deprecated. Port to serve HTTP pages on. Use --web-addr.",
	longName:    "port",
	shortName:   "p",

View on GitHub (pinned to b41aefbe51)

Solutions

Pass a plain decimal integer between 1 and 65535: -p 3000
If you meant to bind an address, use -h for host and -p for port separately
Check for stray whitespace/quotes in wrapper scripts or service unit files

Example fix

# before
./AdGuardHome -p "3000tcp"

# after
./AdGuardHome -p 3000

Defensive patterns

Strategy: validation

Validate before calling

if p, err := strconv.ParseUint(v, 10, 16); err != nil || p == 0 {
    return fmt.Errorf("port must be 1-65535, got %q", v)
}

Type guard

func isValidPort(s string) bool { p, err := strconv.ParseUint(s, 10, 16); return err == nil && p >= 1 }

Prevention

Pass only plain decimal integers to -p
Set defaults in scripts to avoid empty expansions

When it happens

Trigger: Passing -p abc, -p -1, -p 70000, or -p 443.5 on the command line; the value comes from the port option's updateWithValue handler during option parsing.

Common situations: Typos in CLI args, scripts quoting the port wrongly, or copy-pasting an address like 0.0.0.0:3000 into -p (only the number belongs there).

Related errors

AI-assisted analysis of AdguardTeam/AdGuardHome@b41aefbe51 (2026-08-27). Data as JSON: /api/errors/4176a906c565255a. Report an issue: GitHub.