gohugoio/hugo · error

length argument must be an integer

Error message

length argument must be an integer

What it means

Thrown by strings.Substr when called with two variadic arguments and the second (length) cannot be cast to an integer (tpl/strings/strings.go:406-407). The length controls how many characters to extract and must be a whole number; negative lengths are permitted (omit from the end).

Solutions

1. Coerce the length to int: {{ substr .Title 2 (int .Len) }}.
2. Confirm the second variadic is the numeric length, not another string.
3. Store length in front matter as a number.

Example fix

// before
{{ substr .Title 2 .Len }}
// after
{{ substr .Title 2 (int .Len) }}

{{ substr .Title 2 (int .Len) }}

When it happens

Trigger: Calling {{ substr .Title 2 "five" }} or {{ substr .Title 2 .StringLen }} where the second num is non-integer.

Common situations: Passing a human-readable length string ('5 chars'); using a config value typed as string; accidentally passing the ellipsis or a suffix as the length.

Related errors

• start argument must be an integer
• ellipsis must be a string
• text must be a string
• first argument must be a map
• too many arguments passed to truncate

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/d98e06eef1d96908. Report an issue: GitHub.

Appendix: source

Thrown at tpl/strings/strings.go:407

	asRunes := []rune(s)
	rlen := len(asRunes)

	var start, length int

	switch len(nums) {
	case 0:
		return "", errors.New("too few arguments")
	case 1:
		if start, err = cast.ToIntE(nums[0]); err != nil {
			return "", errors.New("start argument must be an integer")
		}
		length = rlen
	case 2:
		if start, err = cast.ToIntE(nums[0]); err != nil {
			return "", errors.New("start argument must be an integer")
		}
		if length, err = cast.ToIntE(nums[1]); err != nil {
			return "", errors.New("length argument must be an integer")
		}
	default:
		return "", errors.New("too many arguments")
	}

	if rlen == 0 {
		return "", nil
	}

	if start < 0 {
		start += rlen
	}

	// start was originally negative beyond rlen
	if start < 0 {
		start = 0
	}

View on GitHub (pinned to 52c9bd7908)