gohugoio/hugo · error

missing 'src' in metadata for resource

Error message

missing 'src' in metadata for resource

What it means

When Hugo assigns metadata to page-bundle resources from the `resources` list in front matter, every metadata entry must contain a `src` key — the glob pattern that selects which resources it applies to. An entry without `src` cannot be matched to anything, so `assignMetadata` fails fast with this error.

Source

Thrown at resources/resource_metadata.go:159

}

// AssignMetadata assigns the given metadata to those resources that supports updates
// and matching by wildcard given in `src` using `filepath.Match` with lower cased values.
// This assignment is additive, but the most specific match needs to be first.
// The `name` and `title` metadata field support shell-matched collection it got a match in.
// See https://golang.org/pkg/path/#Match
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))

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Add a `src` glob to every entry under `resources` in the page's front matter, e.g. `src: "images/*.jpg"` or `src: "**"` for all.
2. Check YAML/TOML indentation so `src` sits inside the same list item as `name`/`title`/`params`.
3. Rename mistaken keys (`source`, `path`, `file`) to `src`.

Example fix

# before
resources:
- name: header
  title: Header image
# after
resources:
- src: "images/header.jpg"
  name: header
  title: Header image

# front matter: every resources entry needs a src glob
[[resources]]
  src = "images/*.jpg"   # required
  title = "Gallery :counter"

When it happens

Trigger: A page bundle's front matter has a `resources:` entry missing `src`, e.g. `resources: [{name: photo, title: Photo}]`; also hit via `CloneWithMetadataFromMapIfNeeded` for any resource in that bundle.

Common situations: Typos like `source:` or `path:` instead of `src`; YAML indentation errors that detach `src` from its list item; copying resource metadata examples incompletely.

Related errors

• failed to match resource with metadata: %w
• error processing file %q
• failed to parse file %q: %s
• failed to convert metadata for file %q: %s
• failed to copy resources to vendor dir: %w

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