gohugoio/hugo · error

invalid anchor value %q in imaging config

Error message

invalid anchor value %q in imaging config

What it means

The site-level `[imaging]` config accepts an `anchor` used for Fill crops. During decode, the value is looked up in the anchorPositions map; if it isn't a recognized anchor name the whole imaging config fails with this error. Valid values include smart, center, topleft, top, topright, left, right, bottomleft, bottom, bottomright.

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 8a468df065)

Solutions

1. Set anchor to a supported value, e.g. `smart`, `center`, `topleft`, `bottomright` (no hyphens or spaces).
2. Remove the anchor key to use the default (smart).

Example fix

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

# after
[imaging]
anchor = "topleft"

valid := map[string]bool{"smart": true, "center": true, "topleft": true, "top": true, "topright": true, "left": true, "right": true, "bottomleft": true, "bottom": true, "bottomright": true}
if !valid[strings.ToLower(anchor)] { /* fix imaging.anchor */ }

When it happens

Trigger: `[imaging]\nanchor = "middle"` or any string not in anchorPositions in hugo.toml; note per-image spec strings hit a different path — this one is specifically the site imaging config.

Common situations: Guessing CSS-like names (`middle`, `top-left` with a hyphen); case is normalized elsewhere but wrong words aren't; typos like `centre`.

Related errors

• %q is not a valid resample filter
• config needs a filename
• invalid color code: %q
• imaging.avif.compression must be one of lossy or lossless, g
• imaging.avif.quality must be between 1 and 100 inclusive, go

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/d3ed00322e2da1e9.json. Report an issue: GitHub ↗.