caddyserver/caddy · error

invalid module name: %v

Error message

invalid module name: %v

What it means

`caddy add-package` wraps splitModule's failure for one of its positional arguments: the argument's module-path portion (text before the last '@') is empty, so it cannot be added. The nested error is 'module name is required'.

Source

Thrown at cmd/packagesfuncs.go:84

}

func cmdAddPackage(fl Flags) (int, error) {
	if len(fl.Args()) == 0 {
		return caddy.ExitCodeFailedStartup, fmt.Errorf("at least one package name must be specified")
	}
	_, nonstandard, _, err := getModules()
	if err != nil {
		return caddy.ExitCodeFailedStartup, fmt.Errorf("unable to enumerate installed plugins: %v", err)
	}
	pluginPkgs, err := getPluginPackages(nonstandard)
	if err != nil {
		return caddy.ExitCodeFailedStartup, err
	}

	for _, arg := range fl.Args() {
		module, version, err := splitModule(arg)
		if err != nil {
			return caddy.ExitCodeFailedStartup, fmt.Errorf("invalid module name: %v", err)
		}
		// only allow a version to be specified if it's different from the existing version
		if _, ok := pluginPkgs[module]; ok && (version == "" || pluginPkgs[module].Version == version) {
			return caddy.ExitCodeFailedStartup, fmt.Errorf("package is already added")
		}
		pluginPkgs[module] = pluginPackage{Version: version, Path: module}
	}

	return upgradeBuild(pluginPkgs, fl)
}

func cmdRemovePackage(fl Flags) (int, error) {
	if len(fl.Args()) == 0 {
		return caddy.ExitCodeFailedStartup, fmt.Errorf("at least one package name must be specified")
	}
	_, nonstandard, _, err := getModules()
	if err != nil {
		return caddy.ExitCodeFailedStartup, fmt.Errorf("unable to enumerate installed plugins: %v", err)

View on GitHub (pinned to 50e54ee279)

Solutions

1. Identify the offending argument (each is validated in order; the first bad one aborts)
2. Rewrite it as a full Go module path, optionally with @version
3. Validate list entries before the loop: every item must match ^[^@\s]+(@[^\s]+)?$

Example fix

# before
for p in '@v1.2.3' 'github.com/mholt/caddy-ratelimit'; do caddy add-package "$p"; done

# after
for p in 'github.com/caddy-dns/cloudflare@v0.2.1' 'github.com/mholt/caddy-ratelimit'; do caddy add-package "$p"; done

for p in "$@"; do [[ "$p" == @* || -z "${p%%@*}" ]] && { echo "bad arg: $p"; exit 1; }; done

When it happens

Trigger: `caddy add-package @v1.0.0`, `caddy add-package @`, or an argument produced by an unset shell variable such that only the version part survives.

Common situations: Looping over a plugin list where one entry is malformed; pasting from release notes that show only `@version` suffixes.

Related errors

• module name is required
• at least one package name must be specified
• package is already added
• too many unflagged arguments
• parsing environment file: %v

AI-assisted analysis of caddyserver/caddy@50e54ee279 (2026-08-15). Data as JSON: /api/errors/73b507417c171448. Report an issue: GitHub.