What causes "command short string is required" in caddyserver/caddy?

Add a Short string to the Command struct before registering

command short string is required

Error message

command short string is required

What it means

RegisterCommand panics when a Command registered from a plugin lacks a Short description. Short is what caddy help and CLI listings display; an empty one means the command was incompletely constructed, which is a programmer error in the plugin, not a runtime condition, hence a panic at init time.

Source

Thrown at cmd/commands.go:589

//   - hyphen cannot be adjacent to another hyphen
//
// This function panics if the name is already registered,
// if the name does not meet the described format, or if
// any of the fields are missing from cmd.
//
// This function should be used in init().
func RegisterCommand(cmd Command) {
	commandsMu.Lock()
	defer commandsMu.Unlock()

	if cmd.Name == "" {
		panic("command name is required")
	}
	if cmd.Func == nil && cmd.CobraFunc == nil {
		panic("command function missing")
	}
	if cmd.Short == "" {
		panic("command short string is required")
	}
	if _, exists := commands[cmd.Name]; exists {
		panic("command already registered: " + cmd.Name)
	}
	if !commandNameRegex.MatchString(cmd.Name) {
		panic("invalid command name")
	}
	defaultFactory.Use(func(rootCmd *cobra.Command) {
		rootCmd.AddCommand(caddyCmdToCobra(cmd))
	})
	commands[cmd.Name] = cmd
}

var commandNameRegex = regexp.MustCompile(`^[a-z0-9]$|^([a-z0-9]+-?[a-z0-9]*)+[a-z0-9]$`)

View on GitHub (pinned to 50e54ee279)

Solutions

Add a Short string to the Command struct before registering
If embedding Caddy as a library, recover the init panic and report which plugin is at fault (check the registration order)

Example fix

// before
caddy.RegisterCommand(caddy.Command{
    Name: "cache-clear",
    Func: clearCache,
})

// after
caddy.RegisterCommand(caddy.Command{
    Name:  "cache-clear",
    Usage: "",
    Short: "Clear the HTTP cache",
    Func:  clearCache,
})

Defensive patterns

Strategy: validation

Validate before calling

if cmd.Short == "" {
    return fmt.Errorf("command %q needs a Short description", cmd.Name)
}

Prevention

Fill Name, Short, and Func in every RegisterCommand call
Write a unit test that registers all your plugin commands to catch panics at test time

When it happens

Trigger: A plugin's init() calls caddy.RegisterCommand(caddy.Command{Name: "foo", Func: ...}) without setting Short; the panic occurs at process start or during tests that import the plugin.

Common situations: Plugin development where the author filled Name and Func but omitted Short; refactors that drop the field; copy-paste of a minimal command skeleton.

Related errors

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