What causes "parsing arg at index %d: %w" in AdguardTeam/AdGuardHome?

Read the wrapped inner error and the index — argv[index] is the offending token

parsing arg at index %d: %w

Error message

parsing arg at index %d: %w

What it means

parseCmdOpts wraps any failure encountered while parsing a single command-line argument, annotating it with the argument's index. The inner error is the real cause — usually 'unknown option', 'got X without argument', or a value parse failure.

Source

Thrown at internal/home/options.go:397

	}

	_, err = fmt.Print(b)
	if err != nil {
		// Exit immediately, since not being able to print out a help message
		// essentially means that the I/O is very broken at the moment.
		exitWithError()
	}
}

// parseCmdOpts parses the command-line arguments into options and effects.
func parseCmdOpts(cmdName string, args []string) (o options, eff effect, err error) {
	next, stop := iter.Pull2(slices.All(args))
	defer stop()

	for i, arg, ok := next(); ok; i, arg, ok = next() {
		o, eff, err = parseArg(cmdName, next, o, eff, arg)
		if err != nil {
			return o, eff, fmt.Errorf("parsing arg at index %d: %w", i, err)
		}
	}

	return o, eff, nil
}

// parseArg parses command-line argument into options and effects.  next and
// eff must not be nil.
func parseArg(
	cmdName string,
	next func() (int, string, bool),
	o options,
	eff effect,
	arg string,
) (newOpt options, newEff effect, err error) {
	opt, found := findMatchingOpt(arg)
	if !found {
		return o, eff, fmt.Errorf("unknown option %s", arg)

View on GitHub (pinned to b41aefbe51)

Solutions

Read the wrapped inner error and the index — argv[index] is the offending token
Run ./AdGuardHome --help to list valid options for your version
Fix or remove the flagged argument and rerun

Example fix

# before
./AdGuardHome --workdir

# after
./AdGuardHome --workdir /var/lib/adguardhome

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-screen argv before exec: run ./AdGuardHome --help parse or lint flags in scripts

Try / catch

if err := loadCmdLineOpts(args); err != nil {
    fmt.Fprintf(os.Stderr, "bad args: %v (index points at the token)", err)
    os.Exit(2)
}

Prevention

Log the full argv when wrapping the binary in scripts
Pin documentation to your binary version

When it happens

Trigger: Passing any malformed flag to the AdGuard Home binary (misspelled long option, option requiring a value at the end of argv, or bad numeric value); loadCmdLineOpts propagates it to Main which prints usage and exits.

Common situations: Typos like --verbose-extra, using flags from a different version (removed/renamed options), or omitting the value for --config / --workdir at the end of the command.

Related errors

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