gohugoio/hugo · error

alignx must be one of left, center, right

Error message

alignx must be one of left, center, right

What it means

Panic while building a Text image filter (images.Text): the 'alignx' option was set to a value other than 'left', 'center', or 'right'. The Text filter draws text onto an image and alignx controls horizontal alignment; only those three strings are valid. This is a template/Go usage error at filter-construction time.

Source

Thrown at resources/images/filters.go:104

	var opt hmaps.Params
	if len(options) > 0 {
		opt = hmaps.MustToParamsAndPrepare(options[0])
		for option, v := range opt {
			switch option {
			case "color":
				if color, ok, _ := toColorGo(v); ok {
					tf.color = color
				}
			case "size":
				tf.size = cast.ToFloat64(v)
			case "x":
				tf.x = cast.ToInt(v)
			case "y":
				tf.y = cast.ToInt(v)
			case "alignx":
				tf.alignx = cast.ToString(v)
				if tf.alignx != "left" && tf.alignx != "center" && tf.alignx != "right" {
					panic("alignx must be one of left, center, right")
				}
			case "aligny":
				tf.aligny = cast.ToString(v)
				if tf.aligny != "top" && tf.aligny != "center" && tf.aligny != "bottom" {
					panic("aligny must be one of top, center, bottom")
				}

			case "linespacing":
				tf.linespacing = cast.ToInt(v)
			case "font":
				if err, ok := v.(error); ok {
					panic(fmt.Sprintf("invalid font source: %s", err))
				}
				fontSource, ok1 := v.(hugio.ReadSeekCloserProvider)
				identifier, ok2 := v.(resource.Identifier)

				if !(ok1 && ok2) {
					panic(fmt.Sprintf("invalid text font source: %T", v))

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Set alignx to exactly one of "left", "center", or "right".
2. Use aligny (top/center/bottom) for vertical alignment instead.
3. If the value comes from front matter, validate/whitelist it before passing to the filter.

Example fix

{{/* before */}}
{{ $f := $images.Text "Hello" (dict "alignx" "middle") }}

{{/* after */}}
{{ $f := $images.Text "Hello" (dict "alignx" "center") }}
{{/* for vertical use aligny */}} {{ $images.Text "Hi" (dict "aligny" "middle" | replace ... ) }}
{{/* note: aligny valid values are top, center, bottom */}}

// Whitelist alignx before building the Text filter.
// Template:  {{ $align := "center" }} {{ if not (in (slice "left" "center" "right") $align) }}{{ $align = "left" }}{{ end }}

func validAlignX(v string) string {
    switch v {
    case "left", "center", "right":
        return v
    }
    return "left" // safe default
}

// Usage: opts["alignx"] = validAlignX(opts["alignx"].(string))

When it happens

Trigger: Calling {{ $images.Text "hello" (dict "alignx" "middle") }} or constructing images.Text with alignx set to an invalid string (e.g. 'top', 'middle', 'start', 'centre'). The panic fires immediately while the filter options are parsed, before any image processing.

Common situations: Template author confuses alignx with aligny or uses CSS-like values ('flex-start', 'justify'). Typos ('centre', 'lef'). Translating from another tool's alignment vocabulary.

Related errors

• too many arguments, expected 0 or 1
• unknown dimension %q
• Shifter is required
• transformerRaw is required
• Transform must be performed with NoShift=true

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