AdguardTeam/AdGuardHome · error

unknown option %s

Error message

unknown option %s

What it means

parseArg could not match the current command-line token against any known long or short option definition (findMatchingOpt returned false). The token is passed to the user verbatim.

Source

Thrown at internal/home/options.go:415

			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)
	}

	if opt.updateWithValue != nil {
		return applyOptWithValue(opt, next, o, eff, arg)
	}

	return applyOptNoValue(opt, cmdName, o, eff, arg)
}

// applyOptNoValue applies option with no value.  eff must not be
// nil.
func applyOptNoValue(
	opt cmdLineOpt,
	cmdName string,
	o options,
	eff effect,
	arg string,
) (newOpt options, newEff effect, err error) {

View on GitHub (pinned to b41aefbe51)

Solutions

1. Check spelling and dash count: long options use --, short use single char (-c, -h, -p)
2. Run ./AdGuardHome --help to see supported options in your build
3. Upgrade/downgrade docs to match your binary version

Example fix

# before
./AdGuardHome -config /etc/adguardhome.yaml

# after
./AdGuardHome -c /etc/adguardhome.yaml

// Validate flags against a known set before launching:
var known = map[string]bool{"--config":true,"-c":true,"--workdir":true,"-w":true,"--host":true,"-h":true,"--port":true,"-p":true}
if !known[arg] && !strings.HasPrefix(arg, "--") { /* reject */ }

When it happens

Trigger: Supplying a flag that AdGuard Home doesn't define: --foobar, single-dash long forms like -config (only -c may be accepted), or options removed in newer releases.

Common situations: Copy-pasting instructions for a different version, using single-dash long options (Go flag-style) where the parser expects double dash, or trailing garbage after a valid command.

Related errors

• parsing port: %w
• parsing arg at index %d: %w
• applying option %s: %w
• got %s without argument
• action %q: %w

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