docker/cli · warning

failed to parse hook template: arg: %dth argument not set

Error message

failed to parse hook template: arg: %dth argument not set

What it means

Returned (wrapped in ErrHookTemplateParse) by commandInfo.argValue when the requested nth positional argument was not provided (n >= NArg). The argValue template func indexes into cobra's positional args; requesting an index beyond what was supplied fails.

Solutions

1. Request argument indices only when the command is known to supply them.
2. Make hook logic conditional on the number of args rather than assuming a fixed arity.
3. Lower the requested index to one that is always present.

flags := cmd.Flags()
if n >= flags.NArg() {
    return fmt.Errorf("argument %d not provided (have %d)", n, flags.NArg())
}

if v, err := msgContext.argValue(n); err != nil {
    // handle missing optional arg
}

When it happens

Trigger: A hook template using {{argValue 2}} on a command invocation that passed fewer than 3 positional arguments.

Common situations: A plugin template that assumes a fixed number of positional args, invoked with optional/missing trailing args, or a subcommand that accepts variadic input.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• failed to parse hook template
• hook template contains too many messages
• failed to parse hook template: flagValue: no flags found
• unexpected hook response type
• failed to unmarshal hook response

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/ffd21cb3e85c465f. Report an issue: GitHub.

Appendix: source

Thrown at cli-plugins/hooks/template.go:92

	if c.cmd == nil {
		return "", fmt.Errorf("%w: flagValue: cmd is nil", ErrHookTemplateParse)
	}
	f := c.cmd.Flag(flagName)
	if f == nil {
		return "", fmt.Errorf("%w: flagValue: no flags found", ErrHookTemplateParse)
	}
	return f.Value.String(), nil
}

// argValue returns the value of the nth argument.
func (c commandInfo) argValue(n int) (string, error) {
	if c.cmd == nil {
		return "", fmt.Errorf("%w: arg: cmd is nil", ErrHookTemplateParse)
	}
	flags := c.cmd.Flags()
	v := flags.Arg(n)
	if v == "" && n >= flags.NArg() {
		return "", fmt.Errorf("%w: arg: %dth argument not set", ErrHookTemplateParse, n)
	}
	return v, nil
}

View on GitHub (pinned to 4f84911bfe)