gohugoio/hugo · error

invalid anchor value

Error message

invalid anchor value %q in imaging config

What it means

Returned by the DecodeConfig buildConfig closure (images package) when imaging.anchor in the site config is non-empty but not one of the recognised anchor positions (Center, TopLeft, Top, TopRight, Left, Right, BottomLeft, Bottom, BottomRight, Smart). The anchor map is keyed by lowercased names, so case is handled, but any other string is rejected.

Solutions

1. Use one of: Center, TopLeft, Top, TopRight, Left, Right, BottomLeft, Bottom, BottomRight, or Smart.
2. Omit the anchor setting to keep the default Smart (smartcrop).
3. Remember the value is lowercased internally, so case does not matter, but spelling does.

Example fix

// before
[imaging]
anchor = "top-left"

// after
[imaging]
anchor = "TopLeft"

var validAnchors = map[string]bool{"center": true, "topleft": true, "top": true, "topright": true, "left": true, "right": true, "bottomleft": true, "bottom": true, "bottomright": true, "smart": true}
func isValidAnchor(s string) bool { return validAnchors[strings.ToLower(s)] }

func isValidImagingAnchor(s string) bool {
    valid := map[string]bool{"center": true, "topleft": true, "top": true, "topright": true, "left": true, "right": true, "bottomleft": true, "bottom": true, "bottomright": true, "smart": true}
    return valid[strings.ToLower(s)]
}

When it happens

Trigger: Setting [imaging] anchor = "top-left" or anchor = "middle" or any value outside the set of nine positions plus "Smart". Fails during Hugo config load at startup.

Common situations: Using a CSS-style hyphenated anchor ("top-left"), "centre" (British spelling), "centerx", or a typo; copying config expecting a different anchor vocabulary.

Related errors

• invalid color code
• invalid jpeg config
• is not a valid resample filter
• config needs a filename
• empty related config provided

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

Appendix: source

Thrown at resources/images/config.go:222

		}

		if err := mapstructure.Decode(m, &i.Imaging); err != nil {
			return i, nil, err
		}

		if err := i.Imaging.init(); err != nil {
			return i, nil, err
		}

		i.BgColor, err = hexStringToColorGo(i.Imaging.BgColor)
		if err != nil {
			return i, nil, err
		}

		if i.Imaging.Anchor != "" {
			anchor, found := anchorPositions[i.Imaging.Anchor]
			if !found {
				return i, nil, fmt.Errorf("invalid anchor value %q in imaging config", i.Imaging.Anchor)
			}
			i.Anchor = anchor
		}

		filter, found := imageFilters[i.Imaging.ResampleFilter]
		if !found {
			return i, nil, fmt.Errorf("%q is not a valid resample filter", filter)
		}

		i.ResampleFilter = filter

		return i, i.Imaging, nil
	}

	ns, err := config.DecodeNamespace[ImagingConfig](in, buildConfig)
	if err != nil {
		return nil, err
	}

View on GitHub (pinned to 52c9bd7908)