caddyserver/caddy · error

module name is required

Error message

module name is required

What it means

splitModule rejects a module argument whose module-path portion is empty. Arguments are split at the LAST '@': everything before is the module path, everything after the version. If nothing precedes the '@', there is no module name to install or remove.

Source

Thrown at cmd/packagesfuncs.go:62

	}

	return upgradeBuild(pluginPkgs, fl)
}

func splitModule(arg string) (module, version string, err error) {
	const versionSplit = "@"

	// accommodate module paths that have @ in them, but we can only tolerate that if there's also
	// a version, otherwise we don't know if it's a version separator or part of the file path
	lastVersionSplit := strings.LastIndex(arg, versionSplit)
	if lastVersionSplit < 0 {
		module = arg
	} else {
		module, version = arg[:lastVersionSplit], arg[lastVersionSplit+1:]
	}

	if module == "" {
		err = fmt.Errorf("module name is required")
	}

	return module, version, err
}

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
	}

View on GitHub (pinned to 50e54ee279)

Solutions

1. Supply the full module path: `caddy add-package github.com/caddy-dns/cloudflare`
2. Include the version only after a complete path: `github.com/caddy-dns/cloudflare@v0.2.1`
3. Check shell variables are set before using them in the package argument

Example fix

# before
caddy add-package @v0.2.1

# after
caddy add-package github.com/caddy-dns/cloudflare@v0.2.1

valid_module() { [[ "$1" =~ ^[^@[:space:]]+(@[^[:space:]]+)?$ ]]; }
valid_module 'github.com/caddy-dns/cloudflare@v0.2.1' || echo 'bad module arg'

When it happens

Trigger: Passing `@v1.2.3` or just `@` to `caddy add-package` / `caddy remove-package`. Also `foo@@v1.2.3`-style typos are fine for the split, but a leading '@' always yields an empty module.

Common situations: Shell quoting mistakes that drop the module path (e.g. `$pkg@v1` with pkg unset → `@v1`), copy-paste from docs that mangled the module path, or tab-completion inserting the version separator first.

Related errors

• at least one package name must be specified
• invalid module name: %v
• download failed: %v
• too many unflagged arguments
• parsing environment file: %v

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