What causes "failed to match resource with metadata: %w" in gohugoio/hugo?

Fix the glob syntax in `src` — balance brackets/braces or escape literal special characters.

failed to match resource with metadata: %w

Error message

failed to match resource with metadata: %w

What it means

After reading a metadata entry's `src` value, Hugo compiles it into a glob via `hglob.GetGlob` to match against resource names. If the pattern is syntactically invalid (e.g. unbalanced brackets or braces), glob compilation fails and this error wraps the underlying glob parse error.

Source

Thrown at resources/resource_metadata.go:166

func assignMetadata(metadata []map[string]any, ma *metaResource, counters map[string]int) error {
	var (
		nameSet, titleSet                   bool
		nameCounter, titleCounter           = 0, 0
		nameCounterFound, titleCounterFound bool
		resourceSrcKey                      = strings.ToLower(ma.Name())
	)

	for _, meta := range metadata {
		src, found := meta["src"]
		if !found {
			return fmt.Errorf("missing 'src' in metadata for resource")
		}

		srcKey := strings.ToLower(cast.ToString(src))

		glob, err := hglob.GetGlob(srcKey)
		if err != nil {
			return fmt.Errorf("failed to match resource with metadata: %w", err)
		}

		match := glob.Match(resourceSrcKey)

		if match {
			if !nameSet {
				name, found := meta["name"]
				if found {
					name := cast.ToString(name)
					// Bundled resources in sub folders are relative paths with forward slashes. Make sure any renames also matches that format:
					name = paths.TrimLeading(filepath.ToSlash(name))
					if !nameCounterFound {
						nameCounterFound = strings.Contains(name, counterPlaceHolder)
					}
					if nameCounterFound && nameCounter == 0 {
						counterKey := "name_" + srcKey
						nameCounter = counters[counterKey] + 1
						counters[counterKey] = nameCounter

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Fix the glob syntax in `src` — balance brackets/braces or escape literal special characters.
If the filename itself contains glob metacharacters, rename the file or use a broader pattern like `images/*`.
Test the pattern mentally against `filepath.Match`/gobwas-glob semantics: `*`, `**`, `?`, `[...]`, `{a,b}` are the supported constructs.

Example fix

# before
resources:
- src: "images/[header.jpg"
# after
resources:
- src: "images/header.jpg"

Defensive patterns

Strategy: validation

Validate before calling

# validate the src glob is well-formed before building
# bad: src = "images/[.jpg"  (invalid glob)
# good: src = "images/*.jpg"

Prevention

Use simple, valid glob patterns in resource metadata `src` (avoid unbalanced brackets).
Test globs against the bundle's actual files with `hugo --printPathWarnings` or a local build before deploying.
Keep resource filenames free of glob metacharacters, or escape them in the pattern.

When it happens

Trigger: A `resources` front-matter entry whose `src` is an invalid glob, e.g. `src: "images/[jpg"` or `src: "{a,b"`; triggered during resource metadata assignment for the bundle.

Common situations: Unescaped `[`, `]`, `{`, `}` in filenames used directly as `src`; copying regex syntax into a glob field; special characters in asset filenames from designers or exports.

Related errors

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